Webhooks de mensagens recebidas do WhatsApp

Quando um contato envia uma mensagem para você, Bird envia whatsapp.received para seu endpoint. O payload usa o envelope de evento WhatsApp e carrega os campos que todo evento de mensagem carrega.

O payload de recebimento

whatsapp.received carrega o conteúdo da mensagem além dos campos que todo evento de mensagem carrega, para que um endpoint possa agir sobre uma mensagem recebida sem precisar lê-la novamente. Um toque em uma mensagem interativa chega como interactive_reply, e in_reply_to_message_id indica a mensagem que ele responde:

Exemplo de código

{
  "data": {
    "direction": "inbound",
    "from": {
      "display_name": "Alex Rivera",
      "phone_number": "+14155550100",
      "username": "alexr"
    },
    "in_reply_to_message_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "interactive_reply": {
      "list": {
        "description": "Next day to 2 days",
        "slug": "priority_express",
        "text": "Priority Mail Express"
      },
      "type": "list"
    },
    "metadata": null,
    "tags": null,
    "to": { "phone_number": "+13124495569" },
    "whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:52:04.118Z",
  "type": "whatsapp.received"
}

Os outros braços de conteúdo seguem a mesma estrutura de um-destes: text, image, video, audio, sticker, document, location, contact_cards e unsupported para um tipo que o API não modela. GET /v1/whatsapp/messages/{message_id} documenta cada um.

Próximos passos

Recebendo mensagens do WhatsApp: todos os braços de conteúdo e busca de mídia recebida
Webhooks de reações: as reações de um contato chegam separadamente
Webhooks de status de mensagens: payloads de entrega e falha para mensagens que você envia

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação