WhatsApp inbound message webhooks

When a contact sends you a message, Bird pushes whatsapp.received to your endpoint. The payload uses the WhatsApp event envelope and carries the fields every message event carries.

The received payload

whatsapp.received carries the message's content on top of the fields every message event carries, so an endpoint can act on an inbound message without reading it back. A tap on an interactive message arrives as interactive_reply, and in_reply_to_message_id names the message it answers:

Code example

{
  "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"
}

The other content arms follow the same one-of-these shape: text, image, video, audio, sticker, document, location, contact_cards, and unsupported for a kind the API does not model. GET /v1/whatsapp/messages/{message_id} documents each one.

Next steps

Receiving WhatsApp messages: every content arm and fetching inbound media
Reaction webhooks: a contact's reactions arrive separately
Message status webhooks: delivery and failure payloads for messages you send

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideConnecting WhatsApp to Bird: from buying a number to a live channel Understand the conceptWhat is the 24-hour customer service window on WhatsApp?Use the toolWhatsApp message builder Explore the capabilityWhatsApp

Try the practice and get an implementation brief