<Intro>

<EndpointHeader />

<Description>

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 a `404`. For the message's current state in a single field, use [Get a WhatsApp message](/docs/api/reference/get-whats-app-message) instead.

</Description>

</Intro>

<Parameters in="path">

<Parameter name="message_id" type="string">

<Description>

ID of the message (`wam_`-prefixed), as returned in the send response's `id` field.

</Description>

</Parameter>

</Parameters>

<Parameters in="query">

<Parameter name="type" type="string">

<Description>

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

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Timeline events for this WhatsApp message, in chronological order. The timeline is bounded and returned in full; this list is not paginated.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

ID of the event (`ev_`-prefixed), unique within the message's timeline.

</Description>

</Field>

<Field name="type" type="string" prefix="data." required>

<Description>

Lifecycle event type. `whatsapp.accepted`: Bird accepted the request. `whatsapp.sent`: handed to the WhatsApp network. `whatsapp.delivered`: delivery confirmed to the recipient's device. `whatsapp.read`: the recipient opened the message (this does not change the message `status`, which never becomes `read`). `whatsapp.failed`: terminal permanent failure. Open enum: new event types may be added over time, so treat any unrecognized value as a future event rather than an error.

</Description>

<Description>

Possible values (may grow over time): `whatsapp.accepted`, `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`

</Description>

</Field>

<Field name="occurred_at" type="string" prefix="data." required>

<Description>

When this event occurred.

</Description>

</Field>

<Field name="error" type="nullable object" prefix="data.">

<Description>

Failure detail. Present only on `whatsapp.failed` events.

</Description>

<FieldChildren kind="response">

<Field name="code" type="string" prefix="data.error." required>

<Description>

Failure reason, uniform whether the failure happened internally or was reported by the WhatsApp network. `insufficient_balance`: the workspace could not afford the send. `price_not_found`: no price was configured for this destination/template combination. `internal_error`: an unexpected Bird-side failure. `undeliverable`: the recipient could not be reached (for example not on WhatsApp, or the number is invalid). `service_window_expired`: the 24-hour customer care window has closed and a free-form message cannot be sent; send a template instead. `rate_limited`: the send was throttled. `recipient_suppressed`: the recipient is on the workspace's suppression list; the message was rejected before sending. Open enum: new codes may be added over time, so treat any unrecognized value as a future code rather than an error.

</Description>

<Description>

Possible values (may grow over time): `insufficient_balance`, `price_not_found`, `internal_error`, `undeliverable`, `service_window_expired`, `rate_limited`, `recipient_suppressed`

</Description>

</Field>

<Field name="description" type="string" prefix="data.error." required>

<Description>

Human-readable explanation of the failure.

</Description>

</Field>

<Field name="meta_error_code" type="nullable string" prefix="data.error.">

<Description>

Raw error code from the WhatsApp Cloud API, when available, for low-level debugging.

</Description>

</Field>

<Field name="occurred_at" type="string" prefix="data.error." required>

<Description>

When the failure occurred.

</Description>

</Field>

</FieldChildren>

</Field>

</FieldChildren>

</Field>

</Payload>