Efetuando/recebendo chamadas de voz(Calling API)
📞 Estabelecimento de Chamada Após Configuração Inicial
Após a configuração do recurso de Chamada de Voz para um determinado PHONE_NUMBER_ID, o aplicativo WhatsApp (do usuário final) passa a exibir o ícone de telefone, indicando que:
A empresa pode iniciar uma chamada para o usuário
O usuário pode iniciar uma chamada para a empresa
A partir desse momento, o fluxo de comunicação entre cliente e servidor pode seguir duas possibilidades distintas, cada uma envolvendo um conjunto diferente de APIs e webhooks.
A) Empresa inicia a chamada (Oferta de Chamada - Call Offer)
A empresa pode iniciar uma chamada para o usuário, mas somente após obter permissão explícita do usuário. Por isso, existem dois passos obrigatórios:
🔵 Passo Obrigatório 1 - Solicitar permissão ao usuário
API: POST /client/{fromPhoneNumberId}/v2/requisicao/mensagem/interativa-permissao-chamada
{
"destinatario": "5521999998888",
"message_id": "wamid.ID",
"textoBody": "Posso ligar?"
}
O usuário deve aceitar, caso contrário, a chamada não pode ser iniciada.
O que acontece depois
Se o usuário aceitar, o WhatsApp enviará ao webhook da empresa:
call_id
status: "allowed"
metadados da permissão
Esse call_id será obrigatório na Oferta da Chamada.
Se o usuário recusar → o fluxo termina.
🟢 Passo Obrigatório 2 - Geração do SDP (Session Description Protocol) pelo cliente via JavaScript (WebRTC – Web Real-Time Communication)
Após o usuário autorizar a operação, o cliente precisa gerar o SDP inicial. O SDP (Session Description Protocol) é o documento que descreve a sessão multimídia — codecs, portas, transportes, capacidades e parâmetros necessários para estabelecer uma conexão de mídia.
Essa geração é feita via WebRTC (Web Real-Time Communication), o protocolo de comunicação em tempo real presente nos navegadores, responsável por criar e negociar pares de mídia (áudio/vídeo/dados).
O SDP é sempre gerado localmente, no próprio navegador. Para isso, o frontend utiliza um objeto RTCPeerConnection e executa o método:
peerConnection.createOffer()
O resultado é o SDP de oferta (offer SDP), que descreve as capacidades de mídia do cliente.
Esse SDP é então enviado ao backend da empresa, que o utilizará para compor a Oferta de Chamada que será enviada ao WhatsApp.
🟣 API utilizada — Início real da chamada (Call Offer)
Após ter:
o call_id autorizado
o SDP gerado pelo cliente WebRTC
o backend envia a Call Offer para o WhatsApp do usuário.
API: POST /waba/{wabaId}/client/{phoneNumberId}/chamada/inicia-chamada
URI
Request (exemplo)
{
"numTelefone": "string",
"sdp": "string"
}
O que acontece em seguida
Após o envio:
O WhatsApp notifica o usuário com a tela nativa de chamada (tocando/chamando).
O backend da empresa receberá eventos no webhook, como:
"status": "REJECTED"
"status": "RINGING"
"status": "ACCEPTED" (contém o SDP de resposta)
"status": "BUSY
Quando o usuário aceitar ("status": "ACCEPTED"), o servidor deve enviar:
API: POST /waba/{wabaId}/client/{phoneNumberId}/chamada/aceita-chamada
URI
Request (exemplo)
{
"callId": "string",
"sdp": "string"
}
Quando o WhatsApp envia call.accepted com o SDP de resposta, a empresa deve usar esse SDP apenas para completar a negociação local, mas deve enviar um NOVO SDP gerado localmente no seu servidor para o endpoint /chamada/aceita-chamada. Após a empresa responder com seu próprio SDP através do endpoint /chamada/aceita-chamada, o WhatsApp entrega esse SDP ao aplicativo do usuário. Nesse momento, a negociação WebRTC é concluída e a chamada é estabelecida, permitindo que a mídia comece a fluir entre as partes.
B) Usuário inicia a chamada
Nesta situação, o usuário toca no ícone de telefone e inicia uma chamada sem que a empresa tenha enviado nada previamente.
Não existe um endpoint “receber chamada”.
O fluxo é dirigido via webhook.
O WhatsApp envia automaticamente para o servidor: Evento recebido
call.offer (Equivalentemente, a oferta inicial da chamada gerada no dispositivo do usuário)
O payload contém:
call_id
direction: "USER_INITIATED"
from (número do usuário)
to (PHONE_NUMBER_ID)
sdp (oferta WebRTC do usuário)
Próxima ação obrigatória da empresa
API utilizada POST /waba/{wabaId}/client/{phoneNumberId}/chamada/aceita-chamada
URI
Request (exemplo)
{
"callId": "string",
"sdp": "string"
}
Após esse passo, a sessão está estabelecida e a troca de mídia pode iniciar.
📌 Importante:
A partir da configuração inicial, o fluxo de estabelecimento da chamada pode começar de qualquer um dos lados, e a empresa deve estar preparada para lidar com ambos.