Calling

Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo permissões, integração SIP e controle de chamadas.

Verificar status de permissão de chamada

get

Verifica se há permissão para iniciar uma chamada de voz para um usuário específico do WhatsApp. A permissão deve ser concedida antes de iniciar a chamada.

Fluxo de Permissão

Enviar uma mensagem solicitando permissão de chamada ao usuário
O usuário concede ou nega a permissão via botões interativos
Consultar este endpoint para verificar o status atual da permissão
Quando concedida, a chamada pode ser iniciada

Estados de Permissão

Permissão

Descrição

GRANTED

Usuário aprovou chamadas recebidas

PENDING

Solicitação enviada, sem resposta ainda

DENIED

Usuário rejeitou a solicitação

EXPIRED

Permissão anterior expirou (tipicamente 24 horas)

NOT_REQUESTED

Nenhuma solicitação foi enviada

Ações Disponíveis

O array actions indica operações disponíveis:

call: Iniciar uma chamada de voz
request_permission: Enviar nova solicitação
none: Nenhuma ação disponível (usuário bloqueado ou indisponível)

Expiração da Permissão

Permissões normalmente expiram 24 horas após concedidas
Usuários podem revogar a permissão a qualquer momento
Uma nova solicitação é necessária após expiração

Boas Práticas

Verificar a permissão antes de tentar ligar
Ter fluxo alternativo por mensagem quando a permissão for negada
Solicitar permissão em contexto apropriado (ex.: após confirmação de agendamento)
Respeitar preferências do usuário e evitar spam de solicitações

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de rota

PHONE_NUMBERstringObrigatório

Número de telefone do destinatário em formato internacional sem o sinal +. Deve incluir o código do país e conter apenas dígitos.

Example: 5511999999999Pattern: ^[0-9]{10,15}$

Respostas

200

Consulta de permissão de chamada bem-sucedida

application/json

messaging_productstringOpcional

Sempre "whatsapp" para a WhatsApp Business API

Example: whatsapp

permissionstring · enumOpcional

Status atual da permissão de chamada para este número. Verifique antes de tentar iniciar uma chamada.

Example: GRANTEDValores possíveis:

401

Não autorizado.

application/json

404

Número de telefone não encontrado ou inválido

application/json

get

/voice/{PHONE_NUMBER}/call-permissions

GET /v1/voice/{PHONE_NUMBER}/call-permissions HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "messaging_product": "whatsapp",
  "permission": "GRANTED",
  "actions": [
    "call"
  ]
}

Obter configuração de chamadas

get

Recupera a configuração atual de chamadas de voz para o número do WhatsApp Business, incluindo integração SIP, horário de atendimento e permissões.

Componentes da Configuração

A resposta inclui:

Componente

Descrição

status

Status geral do recurso de chamadas (ENABLED/DISABLED)

call_icon_visibility

Indica se o ícone de chamada é exibido aos usuários

call_hours

Horário comercial de recebimento de chamadas

callback_permission_status

Indica se a permissão de retorno é obrigatória

sip

Configuração de integração do servidor SIP

Integração SIP

Quando o SIP está configurado, as chamadas são roteadas para o servidor SIP:

hostname: Endereço do servidor SIP
port: Porta do servidor SIP (tipicamente 5060 para UDP, 5061 para TLS)
request_uri_user_params: Parâmetros customizados adicionados ao URI SIP

Horário de Atendimento

Quando call_hours está habilitado:

Chamadas são aceitas apenas no horário configurado
Fora do horário, chamadas são rejeitadas automaticamente
O calendário de feriados substitui o horário semanal regular

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Respostas

200

Configurações de chamada recuperadas com sucesso

application/json

successbooleanOpcional

Indica que a recuperação foi bem-sucedida

401

Não autorizado.

application/json

get

/voice/settings

GET /v1/voice/settings HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Sao_Paulo"
    },
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED"
    }
  }
}

Configurar ajustes de chamada

post

Configura as opções de chamadas de voz do WhatsApp para o número comercial. Inclui habilitar ou desabilitar chamadas, definir horário de atendimento e integração SIP.

Opções de Configuração

Configurações Básicas de Chamada

Configuração

Opções

Descrição

status

ENABLED, DISABLED

Chave mestre para chamadas de voz

call_icon_visibility

DEFAULT, HIDDEN

Exibir ou ocultar o botão de chamada

callback_permission_status

ENABLED, DISABLED

Exige permissão do usuário para chamadas

Horário de Atendimento

Configura quando as chamadas são aceitas:

timezone_id: Fuso horário IANA (ex.: "America/Sao_Paulo")
weekly_operating_hours: Agenda regular por dia da semana
holiday_schedule: Datas de exceção para feriados

Formato de horário: 24 horas HHMM (ex.: "0900" para 9h, "1730" para 17h30)

Integração SIP

Roteia chamadas para a infraestrutura VoIP:

hostname: Endereço do servidor SIP
port: Porta do SIP (padrão 5060)
username/password: Credenciais de autenticação SIP
request_uri_user_params: Parâmetros customizados de URI

Suporte ao Protocolo SIP

UDP: Transporte padrão sem criptografia (porta 5060)
TLS: Transporte criptografado (porta 5061 recomendada)
SRTP: Mídia segura suportada

WebRTC vs SIP

As chamadas podem ser tratadas via:

WebRTC: Tratamento direto no navegador (sem SIP)
SIP: Roteamento para infraestrutura de PBX/contact center

Boas Práticas

Iniciar com horários reduzidos para testar a integração
Usar TLS para conexões SIP em produção
Configurar tratamento de fallback para chamadas perdidas
Monitorar métricas de qualidade de chamada
Manter agentes dedicados durante o horário de atendimento

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Corpo

Respostas

200

Configurações de chamada configuradas com sucesso

application/json

successbooleanOpcional

Indica que a configuração foi salva com sucesso

400

Configuração inválida

application/json

401

Não autorizado.

application/json

post

/voice/settings

POST /v1/voice/settings HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 812

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "TUESDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "WEDNESDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "THURSDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "FRIDAY",
          "open_time": "0900",
          "close_time": "1700"
        }
      ],
      "holiday_schedule": [
        {
          "date": "2026-01-01",
          "start_time": "0000",
          "end_time": "2359"
        },
        {
          "date": "2026-12-25",
          "start_time": "0000",
          "end_time": "2359"
        }
      ]
    },
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "port": 5060,
          "request_uri_user_params": {
            "tenant_id": "abc123",
            "queue": "support"
          }
        }
      ]
    }
  }
}

{
  "success": true
}

Gerenciar chamadas ativas

post

Gerencia operações do ciclo de vida para chamadas de voz ativas do WhatsApp. Este endpoint permite aceitar, rejeitar ou encerrar chamadas.

Visão Geral do Fluxo de Chamada

Webhook de chamada recebida: Um webhook é recebido quando um usuário inicia uma chamada
Pré-aceitação: Preparar o recebimento da chamada e configurar a sessão de mídia
Aceitar: Estabelecer a conexão de áudio
Chamada ativa: Gerenciar a conversação
Encerrar: Finalizar a chamada

Ações

Ação

Quando usar

Campos exigidos

pre_accept

Recebeu chamada, preparando mídia

call_id, session.sdp

Pronto para conectar áudio

call_id, session.sdp

reject

Rejeitar a chamada recebida

call_id apenas

terminate

Encerrar uma chamada ativa

call_id apenas

SDP (Session Description Protocol)

Para ações pre_accept e accept, é necessário fornecer SDP para negociação de mídia:

sdp_type: "answer" (resposta à oferta do chamador)
sdp: Payload SDP completo conforme RFC 8866

O SDP contém:

Codecs de áudio suportados (recomenda-se Opus)
Candidatos ICE para NAT
Impressões digitais DTLS para criptografia
Porta e IP de mídia

Formato do ID da chamada

IDs de chamada seguem o padrão: wacid.{UNIQUE_IDENTIFIER}

Fornecido no webhook de chamada recebida
Deve ser usado exatamente como recebido
Válido durante toda a sessão de chamada

Tratamento de Erros

Cenário

Ação recomendada

ID da chamada não encontrado

A chamada pode ter terminado; registrar e ignorar

Falha na negociação de SDP

Rejeitar a chamada com o motivo apropriado

Timeout no accept

Retornar chamada ou enviar mensagem

Integração WebRTC

Quando SIP não é usado, chamadas são tratadas via WebRTC:

Usar webhooks para receber eventos de chamada
Gerar SDP offer/answer usando bibliotecas WebRTC
Tratar troca de candidatos ICE
Gerenciar fluxos de mídia na aplicação

Autorizações

apikeystringObrigatório

Chave de API para autenticação

Corpo

post

/voice/calls

POST /v1/voice/calls HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 539

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "pre_accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "v=0\\r\\no=- 1234567890 1 IN IP4 192.168.1.100\\r\\ns=-\\r\\nt=0 0\\r\\na=group:BUNDLE audio\\r\\nm=audio 9 UDP/TLS/RTP/SAVPF 111\\r\\nc=IN IP4 0.0.0.0\\r\\na=rtpmap:111 opus/48000/2\\r\\na=fmtp:111 minptime=10;useinbandfec=1\\r\\na=rtcp-mux\\r\\na=setup:active\\r\\na=mid:audio\\r\\na=sendrecv\\r\\na=ice-ufrag:xxxx\\r\\na=ice-pwd:xxxxxxxxxxxxxxxxxxxx\\r\\na=fingerprint:sha-256 XX:XX:XX...\\r\\n"
  }
}

AnteriorFlows PróximoConfigs

Atualizado há 1 mês

Isto foi útil?

Boa tarde

hashtagVerificar status de permissão de chamada

hashtagFluxo de Permissão

hashtagEstados de Permissão

hashtagAções Disponíveis

hashtagExpiração da Permissão

hashtagBoas Práticas

hashtagObter configuração de chamadas

hashtagComponentes da Configuração

hashtagIntegração SIP

hashtagHorário de Atendimento

hashtagConfigurar ajustes de chamada

hashtagOpções de Configuração

hashtagConfigurações Básicas de Chamada

hashtagHorário de Atendimento

hashtagIntegração SIP

hashtagSuporte ao Protocolo SIP

hashtagWebRTC vs SIP

hashtagBoas Práticas

hashtagGerenciar chamadas ativas

hashtagVisão Geral do Fluxo de Chamada

hashtagAções

hashtagSDP (Session Description Protocol)

hashtagFormato do ID da chamada

hashtagTratamento de Erros

hashtagIntegração WebRTC

Verificar status de permissão de chamada

Fluxo de Permissão

Estados de Permissão

Ações Disponíveis

Expiração da Permissão

Boas Práticas

Obter configuração de chamadas

Componentes da Configuração

Integração SIP

Horário de Atendimento

Configurar ajustes de chamada

Opções de Configuração

Configurações Básicas de Chamada

Horário de Atendimento

Integração SIP

Suporte ao Protocolo SIP

WebRTC vs SIP

Boas Práticas

Gerenciar chamadas ativas

Visão Geral do Fluxo de Chamada

Ações

SDP (Session Description Protocol)

Formato do ID da chamada

Tratamento de Erros

Integração WebRTC