whatsapp-messages

List WhatsApp messages

Returns the workspace's WhatsApp messages as a cursor-paginated list, newest first, outbound and inbound alike. Each message carries the one content object it was built from: template, or free-form text, image, video, audio, sticker, document, location, interactive or contact_cards. An inbound message carries interactive_reply when the contact tapped a reply button or a list row, on an interactive message or on a template's quick reply. An inbound message whose content WhatsApp models and we do not carries unsupported instead, naming the type rather than reading back empty. Filter by direction, status, recipient (to), sender (from), business-scoped user ID (bsuid), group (group_id), template category, tag, or creation time. to and from name the same ends of the message the response does, and each accepts an E.164 phone number or a business-scoped user ID. Pair either with direction to search a single side of the message. Neither matches a group, so group_id is what narrows the list to one group's messages. 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.

Messages are retained for 30 days. A created_after earlier than that is accepted and raised to the retention bound rather than rejected, so a wider window returns what is still retained instead of failing. There is no way to read messages older than the window.

get/v1/whatsapp/messages

Request

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

Query parameters

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

created_afterstring date-time
Example:2026-05-01T00:00:00Z

Limits the response to resources created at or after this timestamp. Combine it with created_before to select a time window. Use an RFC 3339 timestamp with a timezone offset.

created_beforestring date-time
Example:2026-06-01T00:00:00Z

Limits the response to resources created before this timestamp. Combine it with created_after to select a time window. Use an RFC 3339 timestamp with a timezone offset.

statusWhatsAppMessageStatus[]

Filter by status. Repeat the parameter to match any of several statuses.

direction'outbound' | 'inbound'

Whether a message was sent from the workspace (outbound) or received by it (inbound).

Filter by whether the business sent the message (outbound) or received it from the contact (inbound).

tostring
Example:+15551234567

Filter by recipient, exact match. The recipient is the contact on an outbound message and your business number on an inbound one, matching the to each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so to=<business-scoped user ID> matches outbound messages only.

fromstring
Example:+13124495648

Filter by sender, exact match. The sender is your business number on an outbound message and the contact on an inbound one, matching the from each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so from=<business-scoped user ID> matches inbound messages only.

phone_numberstring
Example:+15551234567

Deprecated: use to or from instead, which also match a business-scoped user ID. Filters by contact phone number (E.164 exact match), in either direction.

bsuidstring
Example:US.13491208655302741918

Filter by business-scoped user ID (Meta identifier), matching the contact in either direction. to and from also accept one, but each matches a single end of the message.

categorystring

Meta's content classification for a template.

  • authentication: delivers one-time passcodes.
  • utility: delivers transaction-triggered updates (receipts, order status).
  • marketing: carries promotional content.

The category determines the sender number and price. This is an open enum. Accept unrecognized values.

Filter by category.

group_idstring
Example:wag_01krdgeqcxet5s7t44vh8rt9mg

Filter by the WhatsApp group the message belongs to, in either direction: the group an outbound message was addressed to, or the group an inbound message arrived through. Matches the group_id on each message's to. It names one group, so there is no way to ask for the messages that belong to no group: omit it to list group and one-to-one messages together.

tagstring[]

Filter by tag. Accepts name to match any record carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A record must match every tag listed to be returned.

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

Paginated list of WhatsApp messages.

next_cursorstring nullable required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursorstring nullable required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursorstring nullable required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Changes

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