# List conversations

`GET /v1/amb/conversations`

Returns the conversations your business has with customers on Apple
Messages for Business, newest first by last message. To page through
older conversations, use `starting_after`. A closed conversation stays in
this list; filter on `status` to separate them from open ones.

## Code samples

**TypeScript**

```ts
const result = await bird.amb.conversations.list({
  business_id: "abz_01krdgeqcxet5s7t44vh8rt9mg",
  limit: 2,
});
console.log(result);
```

Examples: [TypeScript](/docs/api/reference/list-amb-conversations.ts.md) · [Python](/docs/api/reference/list-amb-conversations.py.md) · [Go](/docs/api/reference/list-amb-conversations.go.md) · [PHP](/docs/api/reference/list-amb-conversations.php.md) · [CLI](/docs/api/reference/list-amb-conversations.cli.md) · [MCP](/docs/api/reference/list-amb-conversations.mcp.md) · [cURL](/docs/api/reference/list-amb-conversations.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
      "business_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "open",
      "origin": "entry_point",
      "entry_point": "support",
      "device_capabilities": [
        "QUICK",
        "LIST",
        "TIME"
      ],
      "supported_content_kinds": [
        "text"
      ],
      "locale": "en-US",
      "last_direction": "outbound",
      "assigned_to": "usr_01krdgeqcxet5s7t44vh8rt9mg",
      "queue": "support",
      "closed_reason": "user_close"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `business_id` (string): Filter to conversations belonging to this business.
- `status` (string)

  Filter to conversations with this status. Omit to return both open and closed conversations.

  Possible values: `open`, `closed`
- `queue` (string): Filter to conversations in this queue. Pass an empty string to match unrouted conversations, the ones no routing rule has claimed.
- `assigned_to` (string): Filter to conversations assigned to this user. Pass `unassigned` to match conversations with no assignee.
- `label` (string): Filter to conversations that have this label.
- `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` 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.

## Response body

- `data` (array of object, required): Page of conversations, newest first by last message.
- `data.id` (string, required): Conversation ID.
- `data.business_id` (string, required): Business this conversation belongs to.
- `data.status` (string, required)

  Whether a conversation is open or closed. There is no close operation on this API: only the customer closes a conversation from their device, and any inbound message on a closed conversation reopens it.

  Possible values: `open`, `closed`
- `data.origin` (string, required)

  How the conversation started. `entry_point` means the customer opened it from one of your configured Apple Messages for Business entry points. `invitation` means the customer accepted an invitation and sent a message. This is set once when the conversation is created and never changes.

  Possible values: `entry_point`, `invitation`
- `data.opaque_user_id` (nullable string, required): Apple's opaque identifier for the customer with this business. The customer must send a message before a conversation is created. Null when no identifier is recorded.
- `data.phone_number` (nullable string, required): Customer phone number, when recorded. Null when unknown. Read the invitation's `to` field for the number an invitation was sent to.
- `data.group_id` (nullable string, required): The `group` value carried by the inbound message that opened or most recently reopened the conversation. Your business chooses it when configuring an entry point with Apple, and Apple passes it through; used with `intent_id` to route the conversation. Null when that message carried none.
- `data.intent_id` (nullable string, required): The `intent` value carried by the inbound message that opened or most recently reopened the conversation. Your business chooses it when configuring an entry point with Apple, and Apple passes it through; used with `group_id` to route the conversation. Null when that message carried none.
- `data.entry_point` (nullable string): The entry point in your channel settings whose group and intent matched the inbound message that opened or most recently reopened the conversation. Null when no configured entry point matched.
- `data.device_capabilities` (array of string, required): The capability tokens the customer's device advertised on its most recent message, replaced by each inbound rather than accumulated, so this describes the device in use now. An empty list means the device's capabilities are unknown. Implemented message types may still be sent, but device rendering support has not been confirmed. Authentication requires an explicitly advertised AUTH2 capability.
- `data.supported_content_kinds` (array of string, required): Implemented baseline types plus interactive types confirmed by `device_capabilities`. An empty capability list yields text, attachments and rich links; it does not establish support for other types. Unadvertised quick replies, list pickers, time pickers and forms are refused when capabilities are known. Custom apps and opaque interactive references are not included because their device support cannot be inferred from these tokens. Unsupported roadmap types cannot be sent.
- `data.locale` (string, required): The customer's locale from the most recent inbound message, or your business's default locale before any inbound arrives. Preserved in Apple's locale format, for example `en_US@rg=nlzzzz`.
- `data.unread_count` (integer, required): Number of inbound messages since this conversation was last marked read. Incremented once per inbound message, reset to zero by marking the conversation read and by any outbound message your workspace sends.
- `data.message_count` (integer, required): Number of messages in this conversation, both directions.
- `data.last_message_at` (string, required): When the most recent message in this conversation was sent or received.
- `data.last_direction` (string, required)

  Direction of the most recent message.

  Possible values: `outbound`, `inbound`
- `data.assigned_to` (nullable string, required): The user this conversation is assigned to, or null when unassigned. Assignment is not rechecked against workspace membership on read, so it can still name a user whose access was removed.
- `data.labels` (array of string, required): Operator-set tags on this conversation. Unlike email, there are no system placement labels: every value here is one an operator chose.
- `data.queue` (string): The console queue this conversation is routed to. Empty when no routing rule matched, which the console lists as unrouted.
- `data.closed_at` (nullable string, required): When this conversation was closed. Null while it is open.
- `data.closed_reason` (nullable string, required): Why this conversation was closed. Null while it is open.
- `data.open_count` (integer, required): Number of times this conversation has been opened, starting at 1 and incremented on each reopen. A closed conversation reopens on the next inbound message rather than creating a new conversation.
- `data.created_at` (string, required): When this conversation was created.
- `data.updated_at` (string, required): When this conversation last changed.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, 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`.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)