Pular para o conteúdo
D-APITestar grátis

chamadas recebidas

Receber ligações de WhatsApp pela API e atender dentro do seu produto

Para receber ligações WhatsApp pela API, o seu SaaS escuta as chamadas em tempo real, mostra quem está ligando e atende pelo navegador ou por um agente de IA, sem custo extra por ligação.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Oferta em tempo real

    Um WebSocket de eventos avisa no instante em que o telefone toca, com callId, quem liga e a sessão que recebeu.

  • Atender devolve o áudio

    POST /calls/accept responde com a wsUrl de mídia, no mesmo formato da ligação de saída. Um código só para os dois sentidos.

  • Recusa com mensagem

    Para quem não atende por voz, a conexão recusa sozinha e responde com o texto que você configurar.

  • Até 20 sessões por socket

    Um único canal de eventos cobre até 20 números, com autorização verificada sessão por sessão.

Receber ligações WhatsApp pela API resolve um problema que todo SaaS com WhatsApp conhece: o cliente final liga para o número da empresa, ninguém vê, e a chamada se perde num celular esquecido na gaveta. Com a D-API, a chamada que entra aparece no painel do seu produto no instante em que toca, com o número de quem liga, e o atendente atende ali mesmo, pelo navegador. Se ninguém puder atender, um agente de voz assume ou a conexão recusa com uma mensagem educada.

O recebimento faz parte das ligações WhatsApp API da D-API e está incluído na conexão não-oficial, sem custo por chamada. Esta página cobre o fluxo inteiro: ativar na conexão, escutar as ofertas, atender, recusar e não se confundir com os eventos.

O que o seu cliente ganha

Pense num software de clínicas. A paciente liga às 8h05 para remarcar; a recepcionista está no painel de agenda do seu produto, vê “ligação de 5511999999999” com o nome do cadastro, atende e já está com a ficha aberta. Na imobiliária, o corretor de plantão atende pelo CRM a ligação que entrou no número do anúncio. No e-commerce, o SAC recebe a ligação no mesmo helpdesk onde estão os tickets daquele cliente.

Em todos os casos, o ganho para o seu SaaS é o mesmo: a voz passa a acontecer dentro do produto, com registro, em vez de num aparelho que ninguém audita.

Como receber ligações de WhatsApp pela API

São quatro passos, e os dois canais envolvidos são independentes: um socket de eventos, único e de longa duração, e um socket de mídia que nasce a cada atendimento.

1. Ative o recebimento na conexão

O recebimento vem desligado. Enquanto estiver assim, você ainda recebe o webhook call.offer, mas a chamada não é atendível pela API.

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 }'

A mudança reinicia a conexão, que fica alguns segundos sem enviar nem receber mensagens. Faça isso uma vez, no onboarding do cliente ou numa janela combinada, e deixe ligado. Para desligar, envie { "receiveCalls": false }. Conexões da API Oficial respondem 400 nessa rota.

2. Escute as ofertas em tempo real

O seu backend abre um WebSocket em wss://api.d-api.cloud/voip/events, com a chave e a lista de sessões na query string (token e sessions). Cada conexão aceita até 20 sessões. A autorização é tudo ou nada: se uma das sessões não for do dono da chave, a assinatura inteira é recusada com unauthorized e o socket fecha com código 1008. Aceita a assinatura, o primeiro frame é { "type": "subscribed", "sessions": [...] }.

A oferta chega assim:

{
  "type": "call.offer",
  "callId": "ABCD1234",
  "from": "[email protected]",
  "callCreator": "201234567890123@lid",
  "timestamp": 1716724496789,
  "sessionId": "minha-sessao"
}

O sessionId vem acrescentado pelo servidor justamente porque um socket cobre vários números e o atendimento precisa saber qual deles tocou. Para um SaaS multi-tenant, isso significa um consumidor por grupo de até 20 conexões, distribuindo cada oferta para o painel do cliente certo.

Esse canal não reenvia histórico. Uma oferta vale poucos segundos e não é atendível depois disso, então reentregar o passado faria a sua interface tocar uma ligação que já acabou. Mantenha o socket aberto com reconexão automática e trate o intervalo de queda como perda de chamadas.

3. Atenda

curl -X POST https://api.d-api.cloud/api/v1/calls/accept \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "minha-sessao", "callId": "ABCD1234", "from": "[email protected]" }'

A resposta traz callId, wsUrl e token, no mesmo formato de POST /calls/stream. Use o callId da resposta dali em diante, porque ele pode diferir do que você enviou. Repassar o from do call.offer é opcional, mas sem ele a chamada fica sem telefone no histórico de ligações.

A partir daí, o áudio funciona igual ao de uma ligação de saída: PCM s16le, 16 kHz, mono, frames de 20 ms. Entregue a wsUrl ao navegador do atendente ou ao processo do seu agente de IA. Se o bridge recusar o atendimento, por exemplo porque a oferta expirou ou foi atendida em outro lugar, a API responde 400 e não entrega uma wsUrl que nunca teria áudio.

4. Ou recuse

POST /calls/reject pede sessionId, callId e from, este exatamente como veio no evento. O WhatsApp recusa contra aquele identificador, então, se o evento trouxe um LID, envie o LID sem transformar em número. A resposta 200 confirma que o comando foi aceito; o call.rejected chega depois, de forma assíncrona.

Os eventos que param o toque

O erro mais comum em integrações de chamada recebida está aqui. No canal de eventos, três tipos encerram o ciclo de uma oferta:

Evento O que significa O que a sua interface faz
call.accepted Atendida fora da sua integração, no celular ou em outro aparelho Para de tocar, a chamada não é sua
call.rejected Recusada fora da sua integração Para de tocar
call.ended Encerrada, em qualquer cenário Para de tocar e limpa o estado

O call.accepted não confirma o seu atendimento. A confirmação é a resposta HTTP do /calls/accept. Quem trata os três eventos como “pare de tocar” e não espera sempre pelo call.ended evita o painel que fica tocando à toa depois que alguém atendeu no aparelho.

Com o SDK, o fluxo cabe em poucas linhas

O d-api-sdk assina os eventos, reconecta sozinho e entrega cada oferta com answer() e reject():

const incoming = await dapi.calls.listen({ sessionIds: ["minha-sessao"] });

incoming.on("call", async (offer) => {
  const call = await offer.answer({ transport: "webrtc" }); // ou: offer.reject()
  call.on("audio", (frame) => bot.hear(frame));
});

incoming.on("withdrawn", (e) => console.log("parou de tocar:", e.callId));

No navegador, o padrão é o mesmo da ligação de saída: o backend atende e entrega { callId, wsUrl } à página, que abre a chamada com WebRTC. O detalhe do transporte está em ligação de WhatsApp no navegador com WebRTC.

Recusar automaticamente, sem perder o registro

Nem todo cliente do seu SaaS quer atender por voz. Para esses, a configuração de chamadas da sessão recusa a ligação e responde por mensagem:

curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/call-settings \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rejectCalls": true, "rejectCallsMessage": "Por aqui atendemos só por mensagem. Pode escrever que já respondemos." }'

O webhook call.offer continua sendo entregue mesmo com a recusa automática ligada. Assim o seu produto ainda mostra “3 pessoas tentaram ligar hoje”, que é justamente o dado que convence o cliente a ativar o atendimento por voz no plano seguinte.

Quando ninguém pode atender

Duas saídas cobrem o fora de horário e o pico. A primeira é recusar pela API com base na regra do cliente (horário comercial, fila cheia) e mandar uma mensagem de retorno. A segunda é um agente de voz com IA vinculado ao número, que espera alguns segundos para o time atender primeiro e só entra se ninguém atender. Esse fluxo está em agente de voz com IA no WhatsApp.

Para o histórico completo, com duração, motivo de encerramento e gravação, os mesmos eventos chegam por webhook, descritos em webhook de chamadas do WhatsApp. O exemplo em Node com assinatura, atendimento e mídia está na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

O recebimento de ligações vem ligado?

Não. Ele vem desligado por padrão e é ativado por conexão com POST /api/v1/sessions/{sessionId}/receive-calls-settings. A mudança reinicia a conexão, que fica alguns segundos sem enviar nem receber mensagens.

E se o meu socket de eventos cair enquanto o telefone toca?

Aquela oferta se perde. O canal não reenvia histórico, porque uma oferta vale poucos segundos. Mantenha o socket aberto com reconexão automática e use os webhooks de chamadas como trilha completa, já que eles continuam chegando em paralelo.

Posso receber ligações em grupo?

O webhook call.offer traz isGroup e, quando for grupo, o groupJid. Use esses campos para separar chamadas de grupo das individuais no seu painel e aplicar a regra que fizer sentido para o seu cliente.

Uma chamada tocando ocupa o canal de voz?

Não. Ofertas recebidas só ocupam canal quando você atende. Uma oferta tocando não impede o seu sistema de iniciar outra ligação.

Dá para usar uma chave restrita no canal de eventos?

Sim. O parâmetro token aceita a chave de usuário ou uma chave com escopo de sessão. Com a chave de sessão, só as sessões dela passam na assinatura.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.