O que é
Inscreva-se em whatsapp.echo_message.created.
Você recebe este evento quando a YCloud registra um eco de saída para um Agent integrado por meio da API REST pública. Leia o conteúdo no formato padrão de mensagem a partir de whatsappMessage; não use este evento para mensagens de entrada de clientes.
O contrato atual mantém o nome do evento inalterado enquanto expõe o eco como uma mensagem padrão do WhatsApp. Campos de roteamento de Agent, handover e Inbox não fazem parte deste payload.
Antes de começar
- Integre o Agent por meio da API REST pública.
- Inscreva um endpoint de webhook ativo na mesma conta em
whatsapp.echo_message.created.
- Verifique
YCloud-Signature em relação ao corpo bruto da requisição, aceite cada evento de forma duradoura e processe-o de maneira idempotente.
Agents criados no console não emitem este webhook de cliente. A sincronização de Inbox deles é um fluxo separado.
Como funciona
Todos os exemplos usam identificadores temporários (placeholders). Roteie pelo type externo e leia whatsappMessage, não whatsappMetaBusinessAgent, whatsappEchoMessage ou data.
Elimine entregas duplicadas com o id externo. O createTime externo é o horário do evento de webhook; campos de horário de mensagem aninhados são horários de origem em RFC 3339.
- Use
id ou wamid para correlacionar eventos de status posteriores.
- Leia o texto de
text.body. Para mídia, inspecione type e o objeto de conteúdo correspondente. Os IDs de mídia não são URLs públicas de download.
- O telefone do cliente e o BSUID são independentes. Quando o callback de origem fornece ambos, o evento inclui
to junto com recipientUserId ou parentRecipientUserId. Identidades ausentes são omitidas e não são inferidas uma da outra.
from é o número de telefone de exibição da empresa quando o callback de origem fornece um número de telefone válido. Ele não é derivado de phoneNumberId.- O contexto de resposta é normalizado para o contrato padrão de mensagem. Por exemplo,
context.id de origem é exposto como context.message_id.
- Campos de Agent, handover, roteamento, preços e conversa não são incluídos.
status é o status armazenado quando o eco é processado; não há garantia de que seja sent.- Mensagens de entrada de clientes usam
whatsapp.inbound_message.received. Ecos do aplicativo comercial usam whatsapp.smb.message.echoes.
Requisição
A YCloud envia esses 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 tarefas lentas de maneira assíncrona.
Eco de texto de saída
Requisição
Armazene o texto de whatsappMessage.text.body. id e wamid vinculam eventos de status subsequentes.
Resposta
Explicação
Leia o texto ecoado de whatsappMessage.text.body. Use id ou wamid para correlacionar eventos de status posteriores.
Eco de imagem de saída
Requisição
O conteúdo da mensagem varia conforme o tipo. Trate os IDs de mídia como referências do provedor, não como URLs públicas de download.
Resposta
Explicação
Use type para selecionar o objeto de conteúdo correspondente. Trate o id de mídia como uma referência do provedor.
Exemplos relacionados
