Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

List messages in a conversation

GET
/v1/amb/conversations/{conversation_id}/messages
const result = await bird.amb.conversations.listMessages(
  "acv_01krdgeqcxet5s7t44vh8rt9mg",
  { limit: 2 },
);
console.log(result);
Réponse200
{
  "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.

Paramètres

conversation_idstring

Conversation identifier. Starts with acv_.

Paramètres de requête

directionstring

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

Possible values: outbound, inbound

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.

Contenu de la réponse

data
array of object
obligatoire

Page of Apple Messages for Business messages, newest first.

Afficher les attributs enfants
data.id
string
obligatoire

ID 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_id
string
obligatoire

The conversation this message belongs to.

data.business_account_id
string
obligatoire

The business the message was sent from or received by.

data.from
string

Apple 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.to
string

Customer'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.direction
string
obligatoire

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.

Possible values: outbound, inbound

data.status
string
obligatoire

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.

Possible values: accepted, sent, send_failed, rejected, received

data.kind
string
obligatoire

Derived 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.source
string

Who sent this message. Absent on an inbound message, which has no source to report.

Possible values: operator, automation, api

data.content
object
obligatoire

Native message content. Outgoing interactions contain requests; incoming interactions contain replies.

Afficher les attributs enfants
data.in_reply_to_message_id
string

Original 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_id
string

Latest customer reply whose in_reply_to_message_id names this message. Omitted until a reply is matched, and in webhook payloads.

data.replied_at
string

When 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.locale
nullable string

Locale 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.category
string

The 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.metadata
object

Arbitrary 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.tags
array of object

Structured {name, value} filter labels applied to this message. Absent on an inbound message.

Afficher les attributs enfants
data.cost
nullable object
obligatoire

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

Afficher les attributs enfants
data.last_error
nullable object

Failure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.

Afficher les attributs enfants
data.created_at
string
obligatoire

The 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_at
nullable string

When 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_ref

Reusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.

Afficher les attributs enfants
data.group
string

Apple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.

data.intent
string

Apple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.

data.requested_language
nullable string
obligatoire

The template language requested by the send, in canonical form. Null when the send named no language or used no template.

data.resolved_language
nullable string
obligatoire

The 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_id
nullable string
obligatoire

The template rendered for this message, or null for a message sent with native content.

data.template_version_id
nullable string
obligatoire

The 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_hash
nullable string
obligatoire

The rendered language's source fingerprint, or null for a message sent with native content.

next_cursor
nullable string
obligatoire

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

prev_cursor
nullable string
obligatoire

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

refresh_cursor
nullable string
obligatoire

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.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation