Skip to main content

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 Meta Business Agent criado via API. Mantenha o conteúdo da mensagem recebido no evento created: 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 em whatsappMessage, correspondendo ao objeto usado pelo evento created correspondente.

Antes de começar

  1. Faça a integração do Agent por meio da API REST pública.
  2. Inscreva um endpoint de webhook ativo na mesma conta em whatsapp.echo_message.updated.
  3. Verifique YCloud-Signature em relação ao corpo bruto da requisição, aceite cada evento de forma durável e processe-o de maneira idempotente.
Agents criados pelo Console não emitem este webhook de cliente. A sincronização de Inbox deles é um fluxo separado.
Consulte Configurar webhooks para obter instruções sobre a configuração do endpoint.

Como funciona

Todos os exemplos usam identificadores temporários. Roteie pelo type externo e leia whatsappMessage, não whatsappMetaBusinessAgent, whatsappEchoMessage ou data. Desduplique entregas repetidas com o id externo. O createTime externo é a hora do evento de webhook; o updateTime aninhado e os horários específicos de status são horários de origem no formato RFC 3339.
  • Faça a correspondência das atualizações com o evento created por id ou wamid, no escopo da 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 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 múltiplos contatos, as identidades ausentes continuam omitidas; elas nunca são inferidas umas a partir das outras.
  • from é incluído somente 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 atrasado de sent pode chegar após read; registre-o sem regredir o status atual.
  • O exemplo de envio tardio abaixo refere-se à mensagem do exemplo lido. O exemplo com falha refere-se a uma mensagem diferente.
  • Status inalterados repetidos de 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 sofrer nova tentativa internamente. Não dependa da ordem de entrega.
  • Status normais de mensagens enviadas por API usam whatsapp.message.updated, não este evento.

Requisição

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

Resposta

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

Mensagem de eco entregue

Requisição

Correlacione com o evento created por id ou wamid. Os eventos atualizados omitem o conteúdo e o tipo da mensagem.

Resposta

Explicação

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

Mensagem de eco lida

Requisição

Correlacione com o evento created por id ou wamid. Os eventos atualizados omitem o conteúdo e o tipo da mensagem.

Resposta

Explicação

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

Status enviado tardio após leitura

Requisição

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

Resposta

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 separada que falhou, não uma transição a partir de lida. As atualizações com falha incluem detalhes do erro de origem quando disponíveis.

Resposta

Explicação

Use errorCode e errorMessage para diagnósticos quando o callback de origem os fornecer.

Exemplos relacionados