List messages in a conversation
/v1/amb/conversations/{conversation_id}/messagesconst result = await bird.amb.conversations.listMessages(
"acv_01krdgeqcxet5s7t44vh8rt9mg",
{ limit: 2 },
);
console.log(result);result = client.amb.conversations.list_messages('acv_01krdgeqcxet5s7t44vh8rt9mg', limit=2)
print(result)for item, err := range client.Amb.Conversations.ListMessages(ctx, "acv_01krdgeqcxet5s7t44vh8rt9mg", bird.AmbConversationsListMessagesParams{Limit: 2}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(item)
}foreach ($bird->amb->conversations->listMessages('acv_01krdgeqcxet5s7t44vh8rt9mg', ['limit' => '2']) as $item) {
var_dump($item);
}bird amb conversations list-messages <conversation-id>curl -X GET "https://us1.platform.bird.com/v1/amb/conversations/{conversation_id}/messages" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"{
"data": [
{
"id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
"business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
"direction": "outbound",
"status": "accepted",
"kind": "text",
"source": "operator",
"in_reply_to_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
"reply_message_id": "amb_01krdgh7m2zq8w4x6y9b3c5d7e",
"replied_at": "2026-10-13T10:09:00Z",
"locale": "en_US",
"category": "order_update",
"tags": [
{
"name": "category",
"value": "welcome"
}
],
"cost": {
"amount": "0.00990",
"currency_code": "USD",
"transaction_amount": "0.00790",
"passthrough_amount": "0.00200"
},
"last_error": {
"code": "bird:business_not_registered",
"description": "Apple refused the message with HTTP status 404."
},
"requested_language": "pt-BR",
"resolved_language": "pt-BR",
"template_id": "amt_01krdgeqcxet5s7t44vh8rt9mg",
"template_version_id": "amv_01krdgeqcxet5s7t44vh8rt9mg",
"template_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
],
"next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
"prev_cursor": null,
"refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
Returns the messages in a conversation, newest first, both received and
sent. To page through older messages, use starting_after. The sort
order is fixed, so to render the messages in conversation order, reverse
the page yourself. Messages do not expire based on age.
参数
conversation_idstringConversation identifier. Starts with acv_.
查询参数
directionstringFilter to received (inbound) or sent (outbound) messages.
Possible values: outbound, inbound
limitintegerMaximum number of items to return per page.
starting_afterstringCursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_beforestringCursor 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.
响应载荷
dataPage of Apple Messages for Business messages, newest first.
显示子属性
data.idID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
data.conversation_idThe conversation this message belongs to.
data.business_account_idThe business the message was sent from or received by.
data.fromApple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
data.toCustomer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
data.directionWhether 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.
Possible values: outbound, inbound
data.statusSend status:
accepted: Accepted and queued for delivery to Apple.sent: Handed to Apple. There is no delivery or read receipt on this channel, sosentis 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. Seelast_errorfor 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. Seelast_error.received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
data.kindDerived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
data.sourceWho sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
data.contentNative message content. Outgoing interactions contain requests; incoming interactions contain replies.
显示子属性
data.content.typeAlways text.
Value: text
data.content.bodyText displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
data.content.subjectSubject displayed above the message body.
data.content.attachmentsOrdered attachments. Each object supplies a source URL or an encrypted Apple reference.
data.content.rich_link_datadata.content.rich_link_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
data.content.rich_link_constructAsks Apple to build the rich link preview when the message is sent, rather than through a prior POST /v1/amb/messages/construct-payload call. No caller holds a signed reference until the send itself resolves one.
data.content.interactive_dataA built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
显示子属性
data.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
data.content.interactive_data.dataExactly one built-in interaction. Protocol versions are managed by Bird.
显示子属性
data.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.quick_replydata.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.list_picker显示子属性
data.content.interactive_data.data.list_picker.sectionsThe menu's sections, each with its own heading and rows.
显示子属性
data.content.interactive_data.data.list_picker.sections.titleHeading shown above this section's rows.
data.content.interactive_data.data.list_picker.sections.orderWhere this section sits relative to its siblings, ascending. Sections omitting it are laid out in list order, after any that specify one.
data.content.interactive_data.data.list_picker.sections.itemsThe rows in this section.
显示子属性
data.content.interactive_data.data.list_picker.sections.items.identifierOpaque item identifier returned in interactive_data.data.list_picker.sections.
data.content.interactive_data.data.list_picker.sections.items.titleLabel shown on the row.
data.content.interactive_data.data.list_picker.sections.items.subtitleSecondary line shown under the title.
data.content.interactive_data.data.list_picker.sections.items.image_identifierIdentifier of an image in interactive_data.data.images, shown next to this row. A key with no matching entry in images is refused with a 422 AMBInteractiveImageInvalid.
data.content.interactive_data.data.list_picker.sections.items.orderPosition within the section, ascending. Defaults to the row's array position.
data.content.interactive_data.data.list_picker.sections.multiple_selectionWhether the customer can select more than one row in this section.
data.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.eventdata.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.dynamicForm content. Bird supplies Apple’s messageForms template and protocol version.
data.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.authenticateAuthentication attempt created through the conversation authentication endpoint. Contains no authorization parameters or credentials.
data.content.interactive_data.data.request_identifierCorrelation identifier for this interaction. Bird generates one when omitted. Use a new value for each message. A reply is linked to its request only when no other sent message in the conversation uses the same identifier.
data.content.interactive_data.data.paymentApple Pay request created through the conversation payment endpoint. Contains no payment token or provider credentials.
data.content.interactive_data.app_idApp Store identifier of the iMessage app.
data.content.interactive_data.app_nameName of the iMessage app.
data.content.interactive_data.bidIdentifier of the iMessage extension, in Apple's com.apple.messages.MSMessageExtensionBalloonPlugin:team-id:extension-id format.
data.content.interactive_data.urlOpaque URL string that Messages passes to the iMessage app.
data.content.interactive_data.use_live_layoutWhether Messages renders the received and reply bubbles using Live Layout.
data.content.interactive_data.session_identifierSession UUID to preserve across interactions. Apple creates one when omitted.
data.content.interactive_data.received_messageContent Messages shows in the received message bubble.
data.content.interactive_data.reply_messageContent Messages shows in the reply message bubble.
data.content.interactive_data.app_icon_source_urlPublicly accessible HTTPS URL of the app's PNG icon. The icon must be smaller than 15 kB. We fetch and include it in the request to Apple. A non-HTTPS URL is refused with a 422 AMBEndpointNotHTTPS. In a template it may contain {{ }} placeholders; the rendered value must be HTTPS.
data.content.interactive_data_refReusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
data.in_reply_to_message_idOriginal message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists, including when more than one sent message in the conversation uses the reply's request identifier.
data.reply_message_idLatest customer reply whose in_reply_to_message_id names this message. Omitted until a reply is matched, and in webhook payloads.
data.replied_atWhen Apple delivered the reply in reply_message_id to Bird. This can be slightly earlier than that reply's created_at, which records when Bird processed it. Omitted until a reply is matched, and in webhook payloads.
data.localeLocale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
data.categoryThe category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
data.metadataArbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
data.tagsStructured {name, value} filter labels applied to this message. Absent on an inbound message.
data.costRecorded per-message charge before MAC pricing. Null in the initial send response, while unpriced, and for MAC-covered replies. MAC fees belong to monthly contact usage, not individual messages. Historical charges have no priced passthrough component.
data.last_errorFailure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
data.created_atThe moment this message was accepted (outbound), or recorded by Bird after Apple delivered it (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
data.sent_atWhen the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
data.data_refReusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
data.groupApple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
data.intentApple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
data.requested_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
data.resolved_languageThe template language whose text was rendered, in canonical form. Null when the send used no template. This can differ from requested_language when the template's fallback policy selects another language.
data.template_idThe template rendered for this message, or null for a message sent with native content.
data.template_version_idThe workspace published version or synthetic built-in version rendered at acceptance, or null for a message sent with native content. For a built-in template, template_content_hash identifies the exact catalogue source.
data.template_content_hashThe rendered language's source fingerprint, or null for a message sent with native content.
next_cursorCursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursorCursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursorRefresh 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.