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

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.

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.