Skip to main content

​
O que é

A YCloud entrega mensagens recebidas do WhatsApp no seu endpoint de Webhook. Depois de aceitar um evento, você pode marcar a mensagem como lida ou exibir um indicador temporário de digitação enquanto sua aplicação prepara uma resposta.

​
Antes de começar

  • Configure um endpoint de Webhook para whatsapp.inbound_message.received.
  • Valide o cabeçalho YCloud-Signature antes de processar eventos.
  • Armazene o id da mensagem recebida.
  • Conecte o número de telefone comercial que recebeu a mensagem.

​
Como funciona

  1. Receba e autentique o evento de Webhook.
  2. Elimine eventos duplicados pelo id do evento.
  3. Extraia o id e o conteúdo da mensagem recebida.
  4. Opcionalmente, marque a mensagem como lida.
  5. Exiba um indicador de digitação somente quando uma resposta estiver sendo preparada.
  6. Envie a resposta com a WhatsApp Messages API.
Marcar uma mensagem como lida também marca as mensagens anteriores da conversa como lidas. O indicador de digitação desaparece quando você responde ou após 25 segundos, o que ocorrer primeiro.

​
Requisição

​
Marcar uma mensagem como lida

POST /whatsapp/inboundMessages/{id}/markAsRead

​
Exibir um indicador de digitação

POST /whatsapp/inboundMessages/{id}/typing
Esta operação também marca a mensagem como lida.

​
Resposta

Uma requisição bem-sucedida retorna HTTP 200 sem corpo de resposta.
A resposta confirma que a ação foi aceita. Ela não envia uma resposta ao usuário do WhatsApp.

​
Orientações de processamento

  • Confirme o recebimento do Webhook antes de iniciar processamentos lentos de IA ou de negócios.
  • Preserve a ordem das mensagens por conversa caso seu caso de uso dependa disso.
  • Trate explicitamente cada type recebido suportado e retenha payloads não suportados para investigação.
  • Use o contexto da mensagem ao responder a uma mensagem recebida específica.

​
Limites e solução de problemas

  • Não exiba um indicador de digitação a menos que uma resposta seja enviada em seguida.
  • Use o ID da mensagem recebida, não o ID do evento de Webhook, no caminho da ação.
  • Torne o processamento de Webhook idempotente, pois a entrega pode ser tentada novamente.
  • Se uma ação falhar, registre o requestId da YCloud sem registrar os conteúdos das mensagens ou credenciais.

Exemplos de payloads recebidos

Inspecione payloads de mensagens de texto, mídia, interativas, de comércio e de sistema.

API de marcação como lida

Inspecione o contrato completo do endpoint.