Mensagem de eco do WhatsApp atualizada

O que é

Assine whatsapp.echo_message.updated. Você recebe este evento quando a YCloud processa um status de eco de saída correspondente para um Agent criado via API. Mantenha o conteúdo da mensagem do evento criado: as atualizações de status omitem o conteúdo da mensagem e type. As atualizações com falha incluem detalhes de erro de origem quando disponíveis. O contrato atual mantém o nome do evento inalterado e expõe as alterações de status sob whatsappMessage, correspondendo ao objeto usado pelo evento criado correspondente.

Antes de começar

Faça a integração do Agent por meio da API REST pública.
Assine um endpoint de webhook ativo na mesma conta em whatsapp.echo_message.updated.
Verifique YCloud-Signature em relação ao corpo bruto da solicitação, aceite cada evento de forma duradoura e processe-o de modo idempotente.

Agents criados pelo Console não emitem este webhook de cliente. A sincronização da Caixa de Entrada deles é um fluxo separado.

Consulte Configurar webhooks para obter instruções sobre a configuração do endpoint.

Como funciona

Todos os exemplos usam identificadores de espaço reservado. Faça o roteamento pelo type externo e leia whatsappMessage, não whatsappMetaBusinessAgent, whatsappEchoMessage ou data. Elimine a duplicação de entregas repetidas com o id externo. O createTime externo é a hora do evento de webhook; o updateTime aninhado e as horas específicas de status são horários de origem no formato RFC 3339.

Faça a correspondência das atualizações com o evento criado por id ou wamid, com escopo definido para sua conta e número comercial.
O telefone do cliente e o BSUID são independentes. Quando o status de origem fornece ambos recipient_id e recipient_user_id, o evento inclui to junto com recipientUserId ou parentRecipientUserId.
Se um item de status omitir essas identidades e o mesmo callback contiver exatamente um contato, a YCloud poderá usar o wa_id e o user_id explícitos desse contato. Com zero ou vários contatos, as identidades ausentes permanecerão omitidas; elas nunca são inferidas uma a partir da outra.
from é incluído apenas quando o callback de origem fornece um número de telefone de exibição comercial válido. Ele não é derivado de phoneNumberId.
Mantenha o histórico de eventos separado do status atual da sua mensagem. Um evento sent tardio pode chegar após read; registre-o sem fazer downgrade do status atual.
O exemplo de envio tardio abaixo refere-se à mensagem do exemplo de leitura. O exemplo com falha refere-se a uma mensagem diferente.
Status inalterados e de mesma classificação repetidos são suprimidos durante o processamento. Isso não garante a entrega HTTP exatamente uma vez.
Um status recebido antes do seu registro de eco correspondente pode ser tentado novamente internamente. Não dependa da ordem de entrega.
Status normais de mensagens enviadas via API usam whatsapp.message.updated, não este evento.

Solicitação

A YCloud envia estes corpos JSON em solicitações HTTP POST para o URL de webhook configurado.

Resposta

Retorne uma resposta 2xx após aceitar cada evento de forma duradoura. Processe tarefas lentas de forma assíncrona.

Mensagem de eco entregue

Solicitação

Faça a correlação com o evento criado por id ou wamid. Eventos atualizados omitem o conteúdo e o tipo da mensagem.

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Registre a transição para entregue e retenha o conteúdo da mensagem recebido no evento criado.

Mensagem de eco lida

Solicitação

Faça a correlação com o evento criado por id ou wamid. Eventos atualizados omitem o conteúdo e o tipo da mensagem.

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Registre a transição para lida usando updateTime e readTime como horários de eventos de origem.

Status de envio tardio após leitura

Solicitação

Um status de origem de classificação inferior pode chegar após a leitura. Registre o evento sem fazer downgrade do status atual da sua mensagem.

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Mantenha este evento no histórico de entrega, mas não faça downgrade de um status atual posterior, como read.

Mensagem de eco com falha

Solicitação

Esta é uma mensagem com falha separada, não uma transição a partir de lida. As atualizações com falha incluem detalhes de erro de origem quando disponíveis.

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550123",
    "to": "+12025550124",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

Resposta

HTTP/1.1 200 OK

Explicação

Use errorCode e errorMessage para diagnóstico quando o callback de origem fornecê-los.

Primeiros passos

Guias

Endpoints

Webhooks

Mensagem de eco do WhatsApp atualizada

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Mensagem de eco entregue

Solicitação

Resposta

Explicação

Mensagem de eco lida

Solicitação

Resposta

Explicação

Status de envio tardio após leitura

Solicitação

Resposta

Explicação

Mensagem de eco com falha

Solicitação

Resposta

Explicação

Exemplos relacionados

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Resposta

​Mensagem de eco entregue

​Solicitação

​Resposta

​Explicação

​Mensagem de eco lida

​Solicitação

​Resposta

​Explicação

​Status de envio tardio após leitura

​Solicitação

​Resposta

​Explicação

​Mensagem de eco com falha

​Solicitação

​Resposta

​Explicação

​Exemplos relacionados

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Mensagem de eco entregue

Solicitação

Resposta

Explicação

Mensagem de eco lida

Solicitação

Resposta

Explicação

Status de envio tardio após leitura

Solicitação

Resposta

Explicação

Mensagem de eco com falha

Solicitação

Resposta

Explicação

Exemplos relacionados