Docs

Receiving & status

The webhook events a WhatsApp Business channel sends — inbound messages, reactions, and the sent, delivered, read lifecycle

A WhatsApp Business channel reports through the same v4 webhooks as every other channel. Create a webhook once and you receive WhatsApp messages alongside iMessage, SMS, and RCS, told apart by channel_type: "whatsapp_business".

Inbound messages

Every message a customer sends arrives as a message.received event, with protocol: "whatsapp_business":

{
  "id": "evt_019fd421-b020-7a63-8f8b-152ea9c99333",
  "type": "message.received",
  "api_version": "2026-10-01",
  "created_at": 1706640000000,
  "organization_id": "org_abc123",
  "data": {
    "message_id": "msg_019fd421-af64-7040-aeae-3e8df24a8e89",
    "chat_id": "chat_019fd421-af64-7040-aeae-3e8df24a8e89",
    "channel_id": "ch_019f959b-ff70-7b1e-9b42-e457bf848fd7",
    "channel_type": "whatsapp_business",
    "kind": "received",
    "direction": "inbound",
    "status": "received",
    "protocol": "whatsapp_business",
    "message_type": "text",
    "text": "Hi, is my order on its way?",
    "sender": "+15551234567",
    "recipient": "+14155550100",
    "contact": {
      "contact_id": "ct_019fd421-af64-7040-aeae-3e8df24a8e8a",
      "identifier": "+15551234567",
      "name": null
    },
    "group": null,
    "channel_address": "+14155550100",
    "attachments": []
  }
}

message_type tells you what the customer sent:

message_type What arrived Where to read it
text A typed message text
media A photo, video, voice note, document, or sticker attachments, plus the caption in text. See Receiving files.
interactive A tap on a reply button, list row, or template quick reply interactive.selected.id. See When the customer taps.
location A shared location text holds the place name, the address, or "latitude, longitude"
contacts A shared contact card text is null

Each inbound message opens or resets the 24-hour customer service window for that chat.

Reactions

When a customer reacts to one of your messages, you receive a message.reaction event. data.message_id is the message they reacted to, data.reaction is the emoji, and data.action is add, or remove when they take the reaction back (then reaction is null).

Status of what you send

Outbound WhatsApp messages move through the standard v4 lifecycle, mapped from Meta's status webhooks and delivered as message.* events:

Status Event Meaning
sent message.sent Meta accepted the message (a wamid was issued)
delivered message.delivered Delivered to the customer's phone
read message.read The customer opened the chat with it
failed message.failed Delivery failed. Inspect error.

Status only moves forward: a late delivered never walks back a read. A request that went out as several WhatsApp messages is still one Blooio message, and receipts from any of its parts move that one message's status.

Note

Customers can turn off read receipts in WhatsApp's privacy settings. Their messages stop at delivered, so don't make read a requirement in your flow.

Reading a message later

The same fields are on the message from GET /v4/chats/{chatId}/messages/{messageId}, and on every message in GET /v4/chats/{chatId}/messages. See the v4 message fields reference for every field.