Skip to main content

O que é

Inscreva-se em whatsapp.echo_message.created. Você recebe este evento quando a YCloud registra um eco de saída para um agente da Meta Business integrado por meio da API REST pública. Leia o conteúdo no formato de mensagem padrão em 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 agente, handover e roteamento da Inbox não fazem parte deste payload.

Antes de começar

  1. Faça a integração do agente por meio da API REST pública.
  2. Inscreva um endpoint de webhook ativo na mesma conta em whatsapp.echo_message.created.
  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.
Agentes criados pelo console não emitem este webhook de cliente. A sincronização de Inbox deles é um fluxo separado.
Consulte Configurar webhooks para configuração do 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. Desduplique entregas repetidas com o id externo. O createTime externo é o horário do evento de webhook; os campos de horário da mensagem aninhada são horários de origem 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 de download públicas.
  • 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 umas das outras.
  • 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 mensagens. Por exemplo, a origem context.id é exposta como context.message_id.
  • Campos de agente, 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 Business App usam whatsapp.smb.message.echoes.

Requisição

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

Resposta

Retorne uma resposta 2xx após aceitar cada evento de forma durável. Processe tarefas lentas de forma 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 de acordo com o tipo. Trate IDs de mídia como referências do provedor, não URLs de download públicas.

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