--- title: "List events for a WhatsApp message" method: GET path: "/v1/whatsapp/messages/{message_id}/events" tags: ["whatsapp-messages"] --- # List events for a WhatsApp message `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` 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](/docs/api/reference/get-whatsapp-message) instead. ## Path parameters - `message_id` string, required ## Query parameters - `type` string: 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. ## Headers - `X-Workspace-Id` string - `X-Organization-Id` string ## Response `200` Event timeline for this WhatsApp message. - WhatsAppEventList - `data` WhatsAppEvent[], required: Timeline events for this WhatsApp message, in chronological order. The timeline is bounded and returned in full; this list is not paginated. - `id` string, required - `type` string, required: 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. - `occurred_at` string, date-time, required: When this event occurred. - `recipient` WhatsAppAddress: Sender or recipient of a WhatsApp message: a phone number, a business-scoped user ID, or both. A message received from a WhatsApp user carries whatever profile they publish, which may be neither. - `phone_number` string: Phone number in E.164 format, when known. - `bsuid` string: Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message. - `group_id` string - `username` string: Present only on a message received from a WhatsApp user, on `from`; never on an outbound send's `to`, where the profile is not known. Absent when the contact has not adopted one, and on a message received before this workspace started recording them. Same form as a number's own username (`WhatsAppNumberProfile.username`), without a leading `@`; a message cannot be addressed by it. - `display_name` string: Present only on a message received from a WhatsApp user, on `from`; never on an outbound send's `to`, where the profile is not known. Absent when the message carries no profile, and on a message received before this workspace started recording them. - `error` WhatsAppError, nullable: Failure detail for a message that could not be delivered or was rejected. - `code` string, required: Standardized failure reason: - `insufficient_balance`: The workspace wallet could not fund the send. - `price_not_found`: No price was configured for the destination and template. - `internal_error`: An unexpected service failure occurred. - `undeliverable`: The recipient could not be reached. - `service_window_expired`: The 24-hour service window closed; send a template. - `rate_limited`: The send was throttled. - `recipient_suppressed`: The recipient is on the workspace suppression list. - `media_rejected`: WhatsApp could not fetch the media URL, or refused the file it found there; `description` carries its reason. This is an open enum. Accept unrecognized values. - `description` string, required: Human-readable explanation of the failure. - `meta_error_code` string, nullable: Raw error code from the WhatsApp Cloud API, when available, for low-level debugging. - `occurred_at` string, date-time, required: When the failure occurred. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error - `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation. --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)