Exemplos de webhook de encerramento e captura de chamadas do WhatsApp

Para o catálogo completo derivado do esquema, consulte todos os exemplos.

O que é

Processe eventos de encerramento, gravação e transcrição de chamadas do WhatsApp.

Antes de começar

Crie um endpoint HTTPS público em sua aplicação.
Configure um endpoint de webhook da YCloud para os tipos de evento necessários.
Armazene o segredo de assinatura do endpoint com segurança.
Torne o processamento de eventos idempotente.

Como funciona

A YCloud envia uma solicitação HTTP POST quando o evento ocorre. Verifique a assinatura, registre o evento de forma durável, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Solicitação

Os cenários abaixo mostram solicitações entregues à sua URL de webhook. Trate o id do evento como o identificador de entrega e use type para rotear o payload.

Resposta

Retorne um status 2xx após aceitar o evento.

HTTP/1.1 200 OK

Para configuração do endpoint, validação de assinatura e comportamento de nova tentativa, consulte Configurar webhooks.

Tanto a empresa quanto o usuário do WhatsApp podem encerrar a chamada a qualquer momento. Quando a empresa ou o usuário do WhatsApp encerra a chamada, você recebe um webhook Call Terminate:

Chamada concluída

Solicitação

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova a duplicidade usando id e mova tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Falha na chamada

Solicitação

{
  "id": "evt_675907f431c55113a751d0e7",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-11T03:33:08.679Z",
  "callingTerminate": {
    "id": "675907a13ae4a901f05fee95",
    "wacid": "wacid.HBgNODYxNTE1NzEzNzYyM",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733826484000,
    "endTime": 1733826637000,
    "duration": 30,
    "status": "FAILED",
    "errorCode": "131000"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova a duplicidade usando id e mova tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Gravação de chamada disponível

Para uma chamada originada via API com a gravação ativada, whatsapp.call.recording.updated informa a disponibilidade da gravação ou uma falha permanente de processamento.

Solicitação

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Use callingRecording.wacid para identificar a chamada e phoneId para identificar o número de telefone comercial. Baixe o mediaAssetId apenas quando status for AVAILABLE. O processamento da gravação é independente do resultado de encerramento da chamada. Para FAILED, inspecione error.code e error.retryable. Consulte gravações e transcrições.

Falha na transcrição da chamada

Para uma chamada originada via API com a transcrição ativada, whatsapp.call.transcription.updated informa a disponibilidade da transcrição ou uma falha permanente de processamento.

Solicitação

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Leia callingTranscription em vez de callingRecording. Neste exemplo, status é FAILED e error.retryable é false. Não tente baixar o asset com falha. Um resultado AVAILABLE usa mediaAssetId para download; o resultado da transcrição é separado do resultado da gravação e do status de encerramento da chamada.

Primeiros passos

Guias

Endpoints

Webhooks

Exemplos de webhook de encerramento e captura de chamadas do WhatsApp

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Chamada concluída

Solicitação

Resposta

Explicação

Falha na chamada

Solicitação

Resposta

Explicação

Gravação de chamada disponível

Solicitação

Resposta

Explicação

Falha na transcrição da chamada

Solicitação

Resposta

Explicação

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Resposta

​Chamada concluída

​Solicitação

​Resposta

​Explicação

​Falha na chamada

​Solicitação

​Resposta

​Explicação

​Gravação de chamada disponível

​Solicitação

​Resposta

​Explicação

​Falha na transcrição da chamada

​Solicitação

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Chamada concluída

Solicitação

Resposta

Explicação

Falha na chamada

Solicitação

Resposta

Explicação

Gravação de chamada disponível

Solicitação

Resposta

Explicação

Falha na transcrição da chamada

Solicitação

Resposta

Explicação