WhatsApp events

Every WhatsApp message emits events as it moves through its lifecycle. Each event is a stamped fact about the message: when Bird accepted it, when it reached WhatsApp, when it was delivered, when the recipient read it, or that it failed. Events are how you follow what happened to a message after the send returns 202.

The lifecycle

A message emits events in order as it progresses. Not every message emits every type — a failed send stops at whatsapp.failed, and whatsapp.read only appears if the recipient opens the message.

Event	Meaning
whatsapp.accepted	Bird accepted the send request. This is what the 202 reported.
whatsapp.sent	Handed to the WhatsApp network.
whatsapp.delivered	Delivery confirmed to the recipient's device.
whatsapp.read	The recipient opened the message.
whatsapp.failed	Terminal, permanent failure. Carries the reason in error.

Two things about whatsapp.read: it does not change the message status (a delivered message stays delivered; the read is recorded as a read_at timestamp), and it only fires when read receipts are available for that conversation.

Reading events from the API

GET /v1/whatsapp/messages/{message_id}/events returns a message's events, oldest first. Reading events needs an API key with the whatsapp_messages scope:

代码示例

curl https://us1.platform.bird.com/v1/whatsapp/messages/wamsg_.../events \
  -H "Authorization: Bearer bk_us1_..."

A message that was accepted, sent, delivered, and read returns four events:

代码示例

{
  "data": [
    {
      "id": "ev_01kx43q96rfm3r1t70pgfqj9sa",
      "type": "whatsapp.accepted",
      "occurred_at": "2026-07-09T18:54:55.962Z",
      "error": null
    },
    {
      "id": "ev_01kx43qb29f9qvxrf5xxm9ft95",
      "type": "whatsapp.sent",
      "occurred_at": "2026-07-09T18:54:57.415Z",
      "error": null
    },
    {
      "id": "ev_01kx43qe1nfbt9vkt6xhw7v00m",
      "type": "whatsapp.delivered",
      "occurred_at": "2026-07-09T18:54:59Z",
      "error": null
    },
    {
      "id": "ev_01kx43qkzzes8vb8r2mjqa8avh",
      "type": "whatsapp.read",
      "occurred_at": "2026-07-09T18:55:05Z",
      "error": null
    }
  ]
}

Each event carries an id, a type, the occurred_at timestamp, and an error. The error is null on every event except whatsapp.failed, where it holds the failure detail.

The same timeline is what the Messages page renders when you open a message.

The WhatsApp message detail sheet in the Bird dashboard, opened for a delivered bird_order_confirmation message: the Events tab showing the per-message lifecycle timeline — Accepted, Sent, Delivered, and Read, each with its timestamp — over the dimmed message list

Webhooks

Webhook events are coming soon. Until then, read events from the API above.

Next steps

WhatsApp messages — the per-message view that renders this timeline
Sending WhatsApp messages — where a message's lifecycle begins