Recebendo Webhook Evento messages.upsert

Como usar o Webhook messages.upsert da API WhatsApp

A API WhatsApp agora possui o evento messages.upsert, que é acionado sempre que uma nova mensagem de texto ou áudio é recebida em sua instância. Este artigo explica como esse evento funciona e como utilizá-lo.

O que este evento faz?

O evento messages.upsert é enviado automaticamente para o webhook configurado na instância sempre que um novo contato envia uma mensagem para seu número do WhatsApp.

Estrutura do Retorno

O payload da requisição enviada para o webhook pode ter diferentes formatos, dependendo do tipo da mensagem recebida.

Exemplo de mensagem de texto

{
  "instance_uuid": "78167818-852a-413a-ad14-57c6942705a8",
  "event": "messages.upsert",
  "date_time": "2025-02-16T14:30:25.123Z",
  "data": {
    "type": "conversation",
    "message": "Olá, tudo bem?",
    "sender": "5598987654321",
    "pushname: "José"
  }
}

Exemplo de mensagem de áudio

{
  "instance_uuid": "78167818-852a-413a-ad14-57c6942705a8",
  "event": "messages.upsert",
  "date_time": "2025-02-16T14:30:25.123Z",
  "data": {
    "type": "audioMessage",
    "audio_url": "https://example.com/audio.mp3",
    "sender": "5598987654321",
    "pushname: "José"
  }
}

Como interpretar os dados?

• instance_uuid: O identificador único da instância que recebeu a mensagem.
• event: O nome do evento (messages.upsert).
• date_time: Data e hora em que a mensagem foi recebida.
• data: Informações específicas da mensagem recebida:
  • type: O tipo da mensagem, podendo ser:
    • conversation: Para mensagens de texto.
    • audioMessage: Para mensagens de áudio.
  • message: O conteúdo da mensagem (presente apenas quando type for conversation).
  • audio_url: URL do arquivo de áudio (presente apenas quando type for audioMessage).
  • sender: O número de telefone do remetente.
  • pushname: Nome do usuário que enviou a mensagem

Como configurar o Webhook?

1. Acesse sua instância na API WhatsApp.
2. No painel de configuração, localize a opção Webhook URL.
3. Insira o URL do seu endpoint que receberá as requisições POST.
4. Certifique-se de que seu servidor está preparado para receber e processar os dados no formato JSON exibido acima.

Conclusão

O evento messages.upsert permite que você receba novas mensagens em tempo real diretamente no seu webhook.

Com ele, sua aplicação pode processar mensagens de texto e áudio automaticamente, tornando a comunicação via WhatsApp mais eficiente e integrada ao seu sistema.