API de ligações WhatsApp para fazer e receber chamadas
Use a API de ligações WhatsApp para fazer e receber chamadas de voz no seu SaaS, com áudio em tempo real e gravação, sem custo extra na API não-oficial.
Time D-API. Atualizado em .7 min de leitura.
Uma API de ligações WhatsApp coloca a chamada de voz dentro do seu produto. A clínica confirma a consulta ligando direto do painel de agenda, o atendente do seu CRM atende o cliente no navegador e o seu agente de IA conversa por voz com quem ligou. Tudo usando o número de WhatsApp que o seu cliente já tem, com o contato atendendo no aplicativo que ele já usa.
Na D-API, fazer e receber ligações está incluído na conexão da API não-oficial, sem custo extra por chamada. O seu SaaS paga a conexão, e voz passa a ser mais uma funcionalidade que você oferece aos seus clientes.
Este guia mostra como cada fluxo funciona com os endpoints reais: ligação de saída com e sem áudio ao vivo, recebimento de chamadas em tempo real, gravação, histórico e os eventos de webhook que fecham o ciclo.
Três jeitos de usar voz no seu SaaS
Antes do código, vale separar os cenários, porque cada um usa uma combinação diferente de endpoints.
Ligação de saída disparada pelo sistema. O seu produto inicia a chamada e acompanha o andamento pelos eventos call.*. Serve para lembrete, confirmação e retorno de atendimento. O endpoint é POST /api/v1/calls/place.
Ligação ao vivo com áudio no seu app. O seu usuário fala pelo microfone do navegador, ou um agente de IA fala pelo servidor, e o áudio trafega nos dois sentidos por WebSocket. O endpoint é POST /api/v1/calls/stream, e a chamada é gravada.
Chamada recebida. Alguém liga para o número do seu cliente, o seu sistema é avisado no instante em que toca e decide se atende ou recusa.
Se o que você precisa é ligar para milhares de contatos com mensagem gravada ou montar uma URA, o caminho é o produto de voz, coberto no artigo sobre URA e disparo de voz por API. Aqui o assunto é a chamada de WhatsApp no número da sessão.
Fazer ligações pela API
O benefício para o seu cliente é ligar sem trocar de ferramenta: o botão “ligar” fica no seu produto, e a chamada sai pelo WhatsApp dele.
A forma mais direta é POST /api/v1/calls/place, que inicia uma chamada 1:1 e responde imediatamente com o callId no estado calling. Toque, atendimento e encerramento chegam depois como eventos de webhook.
Quando o seu produto precisa do áudio, use o modo stream. A chamada recebe a sessão e o número de destino com DDI, só dígitos:
curl -X POST https://api.d-api.cloud/api/v1/calls/stream \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sessionId": "minha-sessao", "phone": "5551999998888" }'
{
"success": true,
"sessionId": "minha-sessao",
"callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"wsUrl": "wss://api.d-api.cloud/voip/stream?callId=a1b2c3d4-...&token=...",
"token": "..."
}
A wsUrl já carrega a autenticação: um token próprio da chamada, nunca a sua API key. Por isso o padrão seguro é iniciar a chamada pelo seu backend, onde a API key fica, e entregar ao navegador apenas a wsUrl, tratada como segredo de curta duração.
O áudio e o ciclo de vida
No WebSocket, frames de texto são eventos e frames binários são áudio. O formato é o mesmo nos dois sentidos: PCM s16le, 16 kHz, mono, em frames de 20 ms (320 amostras, 640 bytes), enviados em cadência de tempo real. Rodar o AudioContext do navegador a 16 kHz evita reamostragem manual.
Os eventos de texto contam a história da chamada: calling, ringing, accepted (o destino atendeu e o áudio está ao vivo), recording, ended com reason (como hangup, rejected, timeout ou terminate) e error. A regra mais importante é não enviar áudio do microfone antes de accepted.
Fechar o WebSocket desliga a chamada. Para manter a ligação durante uma queda de rede, acrescente &resume=1 à wsUrl: o servidor aguarda a reconexão por até 20 segundos e reenvia os eventos desde o início. Pela API HTTP, você também controla a chamada ativa com POST /api/v1/calls/mute, POST /api/v1/calls/end e POST /api/v1/calls/state, que devolve o estado atual (calling, ringing, active e outros).
Há limites claros para planejar a capacidade: por padrão, 10 novas chamadas a cada 60 segundos por usuário (acima disso, a API responde 429) e duração máxima de 3600 segundos por chamada.
Receber ligações em tempo real
Para o seu cliente, receber pela API significa não perder a ligação que entra no WhatsApp da empresa: ela aparece no painel do seu produto, com o contato identificado, e pode ser atendida ali mesmo.
O fluxo tem quatro passos. Primeiro, ligue o recebimento na conexão, que vem desligado por padrão:
curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/receive-calls-settings \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "receiveCalls": true }'
Essa configuração reinicia a conexão, que fica alguns segundos sem enviar nem receber mensagens. Faça a mudança uma vez, em janela controlada, e mantenha ligada.
Depois, abra pelo seu backend um WebSocket em wss://api.d-api.cloud/voip/events, passando a chave e a lista de sessões na query string (até 20 sessões por conexão). A oferta chega como call.offer, com callId, from e o sessionId que recebeu a chamada. Esse canal não reenvia histórico: uma oferta vale poucos segundos, então mantenha o socket aberto continuamente, com reconexão automática.
Para atender, chame POST /api/v1/calls/accept com sessionId e callId. A resposta traz uma wsUrl de mídia idêntica à do modo stream, e daí em diante o áudio funciona exatamente como na ligação de saída. Para recusar, POST /api/v1/calls/reject exige também o from, repassado exatamente como veio, inclusive quando for um LID.
Um detalhe evita um bug clássico. O evento call.accepted avisa que a chamada foi atendida fora da sua integração, no próprio aparelho ou em outro dispositivo conectado. A confirmação de que o seu sistema atendeu é a resposta HTTP de /calls/accept. Trate call.accepted, call.rejected e call.ended como “pare de tocar”.
O exemplo completo em Node, com assinatura de eventos, atendimento e conexão no WebSocket de mídia, está na documentação da D-API.
Recusar automaticamente com uma mensagem
Nem todo cliente do seu SaaS quer atender ligações. Para esses, POST /api/v1/sessions/{sessionId}/call-settings com rejectCalls e rejectCallsMessage recusa a chamada e responde com uma mensagem automática, como “Atendemos só por mensagem, pode escrever aqui”. O call.offer continua sendo entregue no webhook, então o seu produto ainda registra quem tentou ligar.
Webhooks de chamadas, gravação e histórico
Tudo o que acontece nas chamadas também chega por webhook, no mesmo envelope dos demais eventos. É a trilha server-to-server que alimenta relatórios, CRM e auditoria. Se você ainda não montou o recebimento de eventos, o artigo sobre webhook WhatsApp API cobre retentativas, timeout e deduplicação.
Os eventos de saída seguem a ordem call.ringing, call.connected e call.ended. Uma chamada que tocou e não foi atendida gera call.not_answered no lugar de call.ended, o que permite medir taxa de atendimento sem inspecionar o reason. Todos os eventos call.* trazem phone, o telefone da outra ponta só com dígitos:
{
"event": "call.ended",
"sessionId": "minha-sessao",
"data": {
"callId": "ABCD1234",
"state": "idle",
"reason": "hangup",
"peerPn": "[email protected]",
"phone": "5511999999999"
},
"timestamp": "2026-05-26T12:35:40.000Z"
}
Use phone para identificar o contato. Os campos from e callCreator indicam quem iniciou a chamada e, numa ligação feita pela sessão, trazem o número da própria sessão.
Ao fim de uma chamada por stream atendida, o call.audio entrega a gravação com três faixas em WAV mono de 16 kHz: full (mixagem), sender (lado da sessão) e recipient (o contato), além de durationMs. Chamadas não atendidas não geram gravação. Para consultar depois, GET /api/v1/calls lista as chamadas gravadas com paginação (até 100 por página) e filtros por sessionId, phone e recordingStatus, e GET /api/v1/calls/{callId} retorna os metadados de gravação e a transcrição, quando disponível.
Os eventos de chamada vão apenas para o webhook D-API e para o RabbitMQ, e não são enviados para integrações de CRM. Se o seu produto depende de uma dessas integrações, consuma os eventos pelo seu próprio endpoint.
Links e convites de chamada
Às vezes o melhor é deixar o contato escolher a hora. POST /api/v1/calls/create-link cria um link de chamada do WhatsApp, de áudio ou vídeo, que pode ser compartilhado. E POST /api/v1/calls/send-event envia ao destinatário um convite de chamada agendada, com título e horário, usando um link do WhatsApp ou uma URL própria de outra ferramenta de reunião. Para um SaaS de agendamento, isso substitui o lembrete em texto por um convite que o paciente abre no próprio WhatsApp.
Ligações e API Oficial na mesma integração
As chamadas por API exigem uma conexão não-oficial. Para conexões da API Oficial, os endpoints de chamada respondem 400. Na prática, muitos SaaS mantêm os dois tipos no mesmo código: o cliente que precisa de voz usa uma conexão não-oficial, e o cliente que exige a API Oficial usa a Cloud API, com o mesmo preço por conexão na D-API.
Se você vai oferecer as duas opções, vale saber quanto o cliente da API Oficial paga à Meta pelas mensagens antes de montar o plano. A conta é simples: volume previsto por categoria de mensagem multiplicado pela tarifa correspondente na tabela de preços da Meta.
Por onde começar
Comece pela ligação de saída: uma conexão não-oficial de teste, um POST /api/v1/calls/stream feito pelo seu backend e a wsUrl aberta num navegador com o worklet de áudio da documentação. Com o áudio funcionando, ligue o receiveCalls em janela controlada e suba o consumidor de /voip/events com reconexão automática.
Depois, conecte os eventos call.* ao seu banco para ter histórico, taxa de atendimento e gravações por cliente. E se o próximo passo for colocar um agente de IA falando ao telefone, o artigo sobre agentes de IA no WhatsApp mostra como conectar o modelo à D-API.
Veja também: Ligações no WhatsApp, Telefonia e URA, SMS.
Perguntas frequentes
As ligações têm custo adicional?
Não. Fazer e receber ligações de WhatsApp está incluído na conexão da API não-oficial da D-API, sem custo extra por chamada.
Consigo fazer ligações por uma conexão da API Oficial?
Não pela D-API. Os endpoints de chamada exigem uma conexão não-oficial; para conexões Cloud API, rotas como /calls/accept e receive-calls-settings respondem 400.
As chamadas ficam gravadas?
As chamadas feitas por stream são gravadas quando atendidas. A gravação chega no evento call.audio com faixas full, sender e recipient em WAV mono de 16 kHz, e também pode ser consultada em GET /api/v1/calls/{callId}.
Dá para atender uma ligação no navegador do meu usuário?
Sim. O seu backend chama /calls/accept e recebe uma wsUrl de mídia. Você entrega apenas essa URL ao navegador, que troca áudio PCM pelo WebSocket. A API key nunca sai do servidor.
Existe limite de chamadas?
Sim. O padrão é de 10 novas chamadas a cada 60 segundos por usuário, e cada chamada por stream tem duração máxima de 3600 segundos.