Documentation
Sign inGet started
Rozpocznij
Przewodniki
Referencja API
SDK i CLI
Baza wiedzy
Changelog

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.
EventMeaning
whatsapp.acceptedBird accepted the send request. This is what the 202 reported.
whatsapp.sentHanded to the WhatsApp network.
whatsapp.deliveredDelivery confirmed to the recipient's device.
whatsapp.readThe recipient opened the message.
whatsapp.failedTerminal, 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:
Przykład kodu
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:
Przykład kodu
{
  "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