Mensagem de eco do Meta Business Agent atualizada

O que é

Inscreva-se em whatsapp.echo_message.updated. Você recebe este evento quando a YCloud processa um status de eco de saída correspondente para um Meta Business 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. Atualizações com falha incluem detalhes do 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 Agente por meio da API REST Pública.
Inscreva um endpoint de webhook ativo na mesma conta em whatsapp.echo_message.updated.
Verifique YCloud-Signature em relação ao corpo bruto da requisição, aceite cada evento de forma duradoura e processe-o de maneira idempotente.

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

Consulte Configurar webhooks para configurar o endpoint.

Como funciona

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

Faça a correspondência de 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 tanto recipient_id quanto recipient_user_id, o evento inclui to juntamente 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 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 repetidos com a mesma classificação 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 pode ser reenviado internamente. Não dependa da ordem de entrega.
Status de mensagens comuns enviadas por API usam whatsapp.message.updated, não este evento.

Requisição

A YCloud envia estes corpos JSON em requisições HTTP POST para a URL de webhook configurada.

Resposta

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

Mensagem de eco entregue

Requisiçã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 de entrega e retenha o conteúdo da mensagem recebido no evento criado.

Mensagem de eco lida

Requisiçã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 de leitura usando updateTime e readTime como horários do evento de origem.

Status de envio tardio após leitura

Requisição

Um status de origem de classificação mais baixa 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

Requisição

Esta é uma mensagem com falha separada, não uma transição a partir de lida. Atualizações com falha incluem detalhes do 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ósticos quando o callback de origem os fornecer.

Primeiros passos

Guias

Endpoints

Webhooks

Mensagem de eco do Meta Business Agent atualizada

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem de eco entregue

Requisição

Resposta

Explicação

Mensagem de eco lida

Requisição

Resposta

Explicação

Status de envio tardio após leitura

Requisição

Resposta

Explicação

Mensagem de eco com falha

Requisição

Resposta

Explicação

Exemplos relacionados

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Mensagem de eco entregue

​Requisição

​Resposta

​Explicação

​Mensagem de eco lida

​Requisição

​Resposta

​Explicação

​Status de envio tardio após leitura

​Requisição

​Resposta

​Explicação

​Mensagem de eco com falha

​Requisição

​Resposta

​Explicação

​Exemplos relacionados

O que é

Antes de começar

Como funciona

Requisição

Resposta

Mensagem de eco entregue

Requisição

Resposta

Explicação

Mensagem de eco lida

Requisição

Resposta

Explicação

Status de envio tardio após leitura

Requisição

Resposta

Explicação

Mensagem de eco com falha

Requisição

Resposta

Explicação

Exemplos relacionados