whatsapp-messages

List events for a WhatsApp message

Returns a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). The timeline is bounded and returned in full, so this list is not paginated; an unknown message ID returns 404. For the message's current state in a single field, use Get a WhatsApp message instead.

get/v1/whatsapp/messages/{message_id}/events

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}/events
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

message_idstring required
Example:wam_01krdgeqcxet5s7t44vh8rt9mg

ID of the message, as returned in the send response's id field.

Query parameters

typestring

Message timeline event type:

  • whatsapp.accepted: The API accepted the request.
  • whatsapp.sent: The message reached the WhatsApp network.
  • whatsapp.delivered: Delivery to the recipient's device was confirmed.
  • whatsapp.read: The message was read. On an outbound message the recipient opened it; on an inbound one Bird acknowledged it to WhatsApp for the business, which is what a read receipt records.
  • whatsapp.failed: Delivery failed permanently.
  • whatsapp.rejected: The message was refused before sending and not charged.
  • whatsapp.received: An inbound message arrived from the contact.

This is an open enum. Accept unrecognized values.

Example:whatsapp.delivered

Keep only events of this exact type (for example whatsapp.delivered or whatsapp.failed). Omit for the full timeline.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Event timeline for this WhatsApp message.

Example response

{
  "data": [
    {
      "id": "ev_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "whatsapp.delivered",
      "recipient": {
        "phone_number": "+15550001111",
        "bsuid": "NL.xxxx",
        "group_id": "wag_01krdgeqcxet5s7t44vh8rt9mg"
      },
      "error": {
        "description": "Message could not be delivered.",
        "meta_error_code": "131026"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.