whatsapp.call.transcription.updated

Use whatsapp.call.transcription.updated para manipular este evento no seu endpoint de webhook.

Gatilhos

Ocorre quando a transcrição de uma chamada do WhatsApp originada por API fica disponível ou falha permanentemente. Inscreva-se em whatsapp.call.transcription.updated ao configurar seu endpoint de webhook. Este evento relata um estado terminal para um ativo de mídia de chamada originado por API. Use mediaAssetId com a API de download de mídia de chamada quando status for AVAILABLE. Inspecione error quando status for FAILED.

Sintaxe

A YCloud envia uma solicitação HTTP POST para a URL de webhook configurada. A estrutura a seguir mostra uma variante do payload. Valores entre colchetes angulares são marcadores de posição; seus tipos estão listados em Parâmetros. Campos opcionais e outras variantes são descritos abaixo.

{
  "id": "<ID>",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "callingTranscription": {
    "wacid": "<WACID>",
    "phoneId": "<PHONE_ID>",
    "mediaAssetId": "<MEDIA_ASSET_ID>",
    "status": "<STATUS>",
    "error": {
      "code": "<CODE>",
      "retryable": "<RETRYABLE_VALUE>"
    }
  }
}

Parâmetros

Valide o cabeçalho HTTP YCloud-Signature antes de processar o corpo JSON. Consulte a validação de assinatura.

Envelope do evento

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID exclusivo do evento. Tamanho mínimo: `6`. Tamanho máximo: `128`.
`type`	string	Sim	Sempre `whatsapp.call.transcription.updated`.
`apiVersion`	string	Sim	A versão da API usada para renderizar este evento.
`createTime`	string (date-time)	Sim	O momento em que este evento foi criado, formatado em RFC 3339. Ex.: `2022-06-01T12:00:00.000Z`.

Payload do evento

Parâmetro	Tipo	Obrigatório	Descrição
`callingTranscription`	object	Não	Payload de `callingTranscription` específico do evento.

Os quatro campos comuns do envelope são obrigatórios. Os campos do payload dependem da variante do evento. Em cada tabela de objetos, Obrigatório se aplica quando seu objeto pai está presente. Campos opcionais podem ser omitidos; um exemplo não torna um campo obrigatório.

callingTranscription

Parâmetro	Tipo	Obrigatório	Descrição
`wacid`	string	Sim	ID da chamada do WhatsApp.
`phoneId`	string	Sim	ID do número de telefone comercial do WhatsApp usado para a entrega autorizada do ativo.
`mediaAssetId`	string	Sim	ID do ativo de mídia da YCloud usado com a API de download de mídia de chamada.
`status`	string	Sim	Valores: `AVAILABLE`, `FAILED`.
`error`	object	Não	Presente apenas quando `status` for `FAILED`.

callingTranscription.error

Parâmetro	Tipo	Obrigatório	Descrição
`code`	string	Sim	Código de falha estável.
`retryable`	boolean	Sim	Se tentar novamente a operação de mídia upstream pode ter êxito.

Exemplo

O JSON a seguir é o corpo entregue ao seu receptor. IDs, números de telefone e outros valores de conta são ilustrativos. Exemplo de payload quando a transcrição de uma chamada originada por API falha permanentemente

{
  "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
    }
  }
}

Após verificar a assinatura e aceitar o evento de forma duradoura, retorne uma resposta 2xx. Processe trabalhos demorados de forma assíncrona.

HTTP/1.1 200 OK

Para orientações detalhadas de cenários, consulte os exemplos anotados.

Primeiros passos

Guias

Endpoints

Webhook reference

whatsapp.call.transcription.updated

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

callingTranscription

Exemplo

​Gatilhos

​Sintaxe

​Parâmetros

​Envelope do evento

​Payload do evento

​callingTranscription

​Exemplo

Gatilhos

Sintaxe

Parâmetros

Envelope do evento

Payload do evento

callingTranscription

Exemplo