Get a WhatsApp message

GET

/v1/whatsapp/messages/{message_id}

curl -X GET "https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}" \
  -H "Authorization: Bearer $TOKEN"

Returns a single WhatsApp message: its current delivery status, per-stage timestamps (sent_at, delivered_at, read_at), the template it was sent from, and failure detail when it failed. The status advances asynchronously as delivery progresses, so poll this endpoint (or subscribe to whatsapp.* webhook events) after a send to confirm delivery. For the per-event timeline, use List events for a WhatsApp message instead.

Parameter

message_id

string

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

Antwort-Payload

string

erforderlich

ID of the message (wam_-prefixed), assigned when the send is accepted. Pass it as message_id to the get-message and list-events endpoints.

direction

string

erforderlich

Whether the message was sent by the business (outbound) or received from the contact (inbound).

Possible values: outbound, inbound

from

object

erforderlich

Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.

Untergeordnete Attribute anzeigen

from.phone_number

string

Phone number in E.164 format, when known.

from.bsuid

string

Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.

object

erforderlich

Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.

Untergeordnete Attribute anzeigen

to.phone_number

string

Phone number in E.164 format, when known.

to.bsuid

string

Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.

template

object

The template the message was sent from. For authentication templates the filled-in values are not returned.

Untergeordnete Attribute anzeigen

template.name

object

erforderlich

The template's stable handle (for example bird_otp).

template.category

object

erforderlich

Content classification applied to messages sent from this template.

template.language

string

erforderlich

The language code of the template variant that was sent (for example en).

template.components

array of object

erforderlich

The values that filled the template's placeholders. Empty for an authentication template, whose content is never returned.

Untergeordnete Attribute anzeigen

template.components.type

string

erforderlich

Which part of the template this fills in: body for the main text, button for a button's variable, header for the header. Bird manages header values itself, so a header entry supplied on a send is ignored.

Possible values (may grow over time): header, body, button

template.components.parameters

array of object

The values that fill this part's placeholders, in {{n}} placeholder order.

Untergeordnete Attribute anzeigen

template.components.parameters.type

object

erforderlich

The kind of value this parameter carries. text is the only kind today.

template.components.parameters.text

string

erforderlich

The value substituted into the placeholder, as a plain string.

template.components.parameters.name

string

For named-parameter templates: the placeholder this value fills (for example first_name). Omit for positional templates.

status

object

erforderlich

last_error

nullable object

Failure detail for a message that did not reach the recipient. Present only when the message failed.

Untergeordnete Attribute anzeigen

last_error.code

string

erforderlich

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.

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

last_error.description

string

erforderlich

Human-readable explanation of the failure.

last_error.meta_error_code

nullable string

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

last_error.occurred_at

string

erforderlich

When the failure occurred.

created_at

string

erforderlich

When the message was accepted for delivery.

sent_at

nullable string

When the message was handed to the WhatsApp network. Null until then.

delivered_at

nullable string

When delivery was confirmed. Null until then.

read_at

nullable string

When the message was read by the recipient. Null until then.