List WhatsApp messages
GET
/v1/whatsapp/messages
curl -X GET "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"Returns the workspace's WhatsApp messages as a cursor-paginated list, newest first. Filter by status, contact phone number, business-scoped user ID, tag, or creation time; pass the response's next_cursor back as starting_after to fetch the next page. To follow a single message's delivery, use Get a WhatsApp message instead.
Parametry zapytania
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
created_after
string
Return only resources created at or after this timestamp (inclusive lower bound). Combine with created_before to filter to a time window. RFC 3339 / ISO 8601 with timezone.
created_before
string
Return only resources created strictly before this timestamp (exclusive upper bound). Combine with created_after to filter to a time window. RFC 3339 / ISO 8601 with timezone.
status
array
Filter by status. Repeat the parameter to match any of several statuses.
phone_number
string
Filter by contact phone number (E.164 exact match).
bsuid
string
Filter by business-scoped user ID (Meta identifier).
tag
array
Filter by tag. Accepts name to match any message carrying that tag name, or name:value to match a specific tag pair (e.g. category:welcome). Repeat the parameter to AND-combine several tag filters.
Treść odpowiedzi
data
array of object
wymagane
Page of WhatsApp messages, newest first.
Pokaż atrybuty podrzędne
data.id
string
wymagane
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.
data.direction
string
wymagane
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
data.from
object
wymagane
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Pokaż atrybuty podrzędne
data.from.phone_number
string
Phone number in E.164 format, when known.
data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
data.to
object
wymagane
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Pokaż atrybuty podrzędne
data.to.phone_number
string
Phone number in E.164 format, when known.
data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
data.template
object
The template the message was sent from. For authentication templates the filled-in values are not returned.
Pokaż atrybuty podrzędne
data.template.name
object
wymagane
The template's stable handle (for example bird_otp).
data.template.category
object
wymagane
Content classification applied to messages sent from this template.
data.template.language
string
wymagane
The language code of the template variant that was sent (for example en).
data.template.components
array of object
wymagane
The values that filled the template's placeholders. Empty for an authentication template, whose content is never returned.
Pokaż atrybuty podrzędne
data.template.components.type
string
wymagane
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
data.template.components.parameters
array of object
The values that fill this part's placeholders, in {{n}} placeholder order.
Pokaż atrybuty podrzędne
data.template.components.parameters.type
object
wymagane
The kind of value this parameter carries. text is the only kind today.
data.template.components.parameters.text
string
wymagane
The value substituted into the placeholder, as a plain string.
data.template.components.parameters.name
string
For named-parameter templates: the placeholder this value fills (for example first_name). Omit for positional templates.
data.status
object
wymagane
data.last_error
nullable object
Failure detail for a message that did not reach the recipient. Present only when the message failed.
Pokaż atrybuty podrzędne
data.last_error.code
string
wymagane
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
data.last_error.description
string
wymagane
Human-readable explanation of the failure.
data.last_error.meta_error_code
nullable string
Raw error code from the WhatsApp Cloud API, when available, for low-level debugging.
data.last_error.occurred_at
string
wymagane
When the failure occurred.
data.created_at
string
wymagane
When the message was accepted for delivery.
data.sent_at
nullable string
When the message was handed to the WhatsApp network. Null until then.
data.delivered_at
nullable string
When delivery was confirmed. Null until then.
data.read_at
nullable string
When the message was read by the recipient. Null until then.
data.tags
array of object
Structured {name, value} filter labels applied to this message.
Pokaż atrybuty podrzędne
data.tags.name
string
wymagane
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
wymagane
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
data.metadata
object
Arbitrary JSON metadata stored on the message.
next_cursor
nullable string
wymagane
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
wymagane
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
wymagane
Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.