eventos de chamada
Webhook de chamadas do WhatsApp para registrar cada ligação no seu produto
O webhook de chamadas do WhatsApp avisa o seu SaaS de cada ligação no número do cliente: quem ligou, quem atendeu, quem não atendeu, quanto durou e onde está a gravação, no mesmo envelope dos outros eventos.
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
Contato sempre em phone
Todo evento call.* traz phone, o telefone da outra ponta só com dígitos, nas chamadas feitas e recebidas.
Não atendida tem evento próprio
call.not_answered substitui o call.ended quando a ligação de saída tocou e ninguém atendeu.
Um call.ended por chamada
Eventos duplicados de encerramento são deduplicados por callId antes de chegar ao seu endpoint.
Gravação no evento
No modo stream, call.audio entrega as URLs das faixas full, sender e recipient, com duração e tamanho.
O webhook de chamadas do WhatsApp é o que transforma ligação em dado. Sem ele, o seu cliente sabe que “o telefone tocou bastante hoje”. Com ele, o seu SaaS mostra quantas ligações a recepção recebeu e atendeu, quantas entraram depois do expediente e qual foi a taxa de atendimento das ligações de confirmação da agenda em cada dia da semana. Cada número desses sai de um evento call.* que chega no seu endpoint.
Os eventos fazem parte das ligações WhatsApp API da D-API e chegam no webhook por sessão, no envelope comum { event, sessionId, data, timestamp, traceId? }, com retentativa e backoff exponencial como qualquer outro evento. O guia geral de recebimento, com deduplicação e timeout, está no artigo webhook WhatsApp API.
Os eventos do webhook de chamadas
| Evento | Direção | Quando chega |
|---|---|---|
call.offer |
Entrada | O número da sessão está recebendo uma chamada |
call.accepted |
Entrada | A chamada recebida foi atendida em outro dispositivo |
call.rejected |
Entrada ou saída | Recusada pela sessão ou pelo contato |
call.ringing |
Saída | Primeiro evento da ligação de saída, assim que é discada |
call.connected |
Saída | O contato atendeu, estado active |
call.ended |
Entrada ou saída | Encerrada; na saída, só se foi atendida |
call.not_answered |
Saída | Tocou e ninguém atendeu |
call.audio |
Saída | Áudio ou gravação da chamada |
As ligações de saída vêm de POST /calls/place ou POST /calls/stream, descritas em fazer ligações de WhatsApp pela API. As de entrada são as que tocam no número do seu cliente, tema de receber ligações de WhatsApp pela API.
Quem é o contato: use phone
Todo evento call.* traz phone: o telefone da outra ponta, só dígitos, sem sufixo. Nunca é o número da própria sessão, em nenhuma direção. É o campo para casar a ligação com o cadastro do contato no seu banco.
Quando o WhatsApp informa só um LID sem telefone conhecido, phone vem null e o LID aparece em lid. Os campos from e callCreator continuam no payload por compatibilidade, mas indicam quem iniciou a chamada; numa ligação feita pela sessão, os dois trazem o número da própria sessão. Usar from para identificar o contato é o bug mais comum nessa integração.
Chamada recebida: call.offer
{
"event": "call.offer",
"sessionId": "minha-sessao",
"data": {
"callId": "ABCD1234",
"phone": "5511999999999",
"from": "5511999999999",
"callCreator": "5511999999999",
"isGroup": false,
"timestamp": 1716724496789
},
"timestamp": "2026-05-26T12:34:56.789Z",
"traceId": "a1b2c3d4-..."
}
isGroup indica chamada de grupo, e nesse caso groupJid vem preenchido. O call.offer é entregue mesmo com a recusa automática de chamadas ligada, então o seu produto registra a tentativa de contato de qualquer forma.
Chamada de saída: do toque ao fim
Os eventos de saída compartilham o mesmo payload base: callId, state, reason (só no call.ended), peerLid e peerPn opcionais, e o phone. A sequência de uma ligação atendida é call.ringing (estado ringing), call.connected (estado active) e call.ended (estado idle, com reason).
Duas garantias simplificam o seu código. Uma chamada gera exatamente um call.ended, porque eventos duplicados de encerramento são deduplicados por callId. E uma ligação de saída que tocou e ninguém atendeu gera call.not_answered, com estado idle e reason: "no_answer", no lugar do call.ended. Taxa de atendimento vira connected / (connected + not_answered), sem interpretar motivo.
Chamadas não atendidas não geram gravação nem call.audio.
call.accepted e call.rejected
call.accepted avisa que uma chamada recebida foi atendida em outro dispositivo, como o próprio celular do cliente. call.rejected cobre os dois sentidos: a chamada recebida que a sessão recusou e a ligação feita pela sessão que o contato recusou. Nos dois, phone é o contato.
O payload desses dois eventos é repassado como vem do bridge, e os campos garantidos são callId e phone. Programe contra esses dois e trate o resto como opcional. Para o painel do seu cliente, call.accepted é o dado que mostra quantas ligações o time ainda atende pelo celular, um bom argumento para migrar o atendimento para dentro do seu produto.
call.audio: duas variantes
O call.audio muda de forma conforme o modo da ligação.
Pedaços ao vivo. Numa ligação por /calls/place com recordAudio: true, o áudio do contato chega em pedaços de cerca de 1 segundo, ordenados por seq, com sampleRate 16000, channels 1, encoding pcm_s16le, o áudio em base64 em data e final: true no último. São cerca de um evento por segundo por chamada, então habilite só se for consumir.
Gravação pronta. Numa ligação por /calls/stream que foi atendida, chega um único evento ao final:
{
"event": "call.audio",
"sessionId": "minha-sessao",
"data": {
"callId": "ABCD1234",
"files": {
"full": "https://.../calls/ABCD1234.wav",
"sender": "https://.../calls/ABCD1234-sender.wav",
"recipient": "https://.../calls/ABCD1234-recipient.wav"
},
"durationMs": 12000,
"sizeBytes": 384044,
"mimetype": "audio/wav"
},
"timestamp": "2026-05-26T12:35:40.000Z"
}
As faixas são WAV mono de 16 kHz: full é a mixagem, sender o lado da sessão e recipient o contato. O campo url, quando presente, é um alias depreciado de files.full.
Um handler que dá conta de tudo
O esqueleto abaixo grava cada ligação no banco do seu SaaS. Ele responde rápido e deixa o trabalho pesado para depois, como pede qualquer webhook.
app.post("/webhooks/d-api", async (req, res) => {
res.sendStatus(200); // responda antes de processar
const { event, sessionId, data } = req.body;
if (!event?.startsWith("call.")) return;
const tenant = await tenantPorSessao(sessionId);
const contato = data.phone ?? data.lid ?? null; // nunca use from
switch (event) {
case "call.offer":
return ligacoes.registrarEntrada(tenant, data.callId, contato);
case "call.connected":
return ligacoes.marcarAtendida(tenant, data.callId);
case "call.not_answered":
return ligacoes.marcarNaoAtendida(tenant, data.callId, contato);
case "call.ended":
return ligacoes.encerrar(tenant, data.callId, data.reason);
case "call.audio":
if (data.files) return ligacoes.anexarGravacao(tenant, data.callId, data.files, data.durationMs);
}
});
Use callId como chave idempotente: com retentativa, o mesmo evento pode chegar mais de uma vez. O sessionId do envelope é o que separa um cliente do outro num SaaS multi-tenant.
Fora do webhook
Os eventos de chamada são despachados apenas para o webhook D-API e para o RabbitMQ da sessão; eles não vão para integrações de CRM. Se o seu produto consome eventos por fila, as chamadas chegam pelo mesmo caminho, como descrito em WhatsApp com RabbitMQ. Os demais eventos da conexão, como mensagens e status, estão em eventos de webhook do WhatsApp. A referência campo a campo está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Os eventos de chamada chegam nas integrações de CRM?
Não. Eventos de chamada vão apenas para o webhook D-API e para o RabbitMQ da sessão. Se o seu produto depende de uma integração de CRM, consuma as chamadas pelo seu próprio endpoint e repasse.
Recebo call.offer mesmo com a recusa automática ligada?
Sim. O call.offer é entregue mesmo com rejectCalls ativo, o que permite registrar quem tentou ligar para um cliente que não atende por voz.
Qual a diferença entre o webhook e o socket /voip/events?
O socket entrega ofertas em tempo real para atender na hora e não reenvia histórico. O webhook é a trilha server-to-server com retentativa, ideal para banco, relatório e auditoria. Os dois rodam em paralelo.
Os eventos da URA são os mesmos?
Não. Os eventos de URA usam outro envelope, com channel voice e bulkCallId. Os eventos call.* desta página são só das chamadas de WhatsApp no número da sessão.
O phone pode vir vazio?
Pode vir null quando o WhatsApp só informou um LID sem telefone conhecido. Nesse caso o LID vem no campo lid. Não use os dígitos do LID como número de telefone.