amb-messages

List messages

Returns your business's Apple Messages for Business messages across conversations, newest first, both received and sent. To page through older messages, use starting_after. Messages do not expire based on age.

To list messages within a single conversation, use listAMBConversationMessages.

get/v1/amb/messages

Request

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

Query parameters

conversation_idstring
Example:acv_01krdgeqcxet5s7t44vh8rt9mg

Filter to messages belonging to this conversation.

business_account_idstring
Example:abz_01krdgeqcxet5s7t44vh8rt9mg

Filter to messages belonging to this business.

direction'outbound' | 'inbound'

Whether a message was sent by the business or received from the customer:

  • outbound: A reply the business sent into the conversation.
  • inbound: A message the customer sent.

Filter to received (inbound) or sent (outbound) messages.

status'accepted' | 'sent' | 'send_failed' | 'rejected' | 'received'

Send status:

  • accepted: Accepted and queued for delivery to Apple.
  • sent: Handed to Apple. There is no delivery or read receipt on this channel, so sent is the furthest an outbound message's status advances.
  • send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. See last_error for why sending stopped.
  • rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. See last_error.
  • received: Received as an inbound message.

Filter to messages with this status.

kind'text' | 'attachment' | 'rich_link' | 'quick_reply' | 'list_picker' | 'time_picker' | 'form' | 'apple_pay' | 'authenticate' | 'imessage_app' | 'interactive'

Derived message classification for filtering and statistics. Send requests use the native content.type families. Create Apple Pay and authentication requests through the conversation payment and authentication operations.

  • text: Text, optionally with a subject.
  • attachment: One or more files, images, audio clips, or videos.
  • rich_link: A link with a preview card.
  • quick_reply: Two to five reply choices.
  • list_picker: A grouped menu of choices.
  • time_picker: Appointment time slots; a reply may contain only a selected label.
  • form: A multi-page form.
  • imessage_app: A custom iMessage app interaction on a compatible device.
  • interactive: An opaque interactive reference whose subtype is unknown.
  • apple_pay: An Apple Pay request created through the conversation payment operations.
  • authenticate: An identity verification request created through the conversation authentication operations.

Filter to messages whose content is this shape.

categorystring

Filter to outbound messages sent with this category, exact match.

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.

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.

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.

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 messages.

AMBMessageList required(unresolved $ref)

Changes

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