---
title: "List messages"
method: GET
path: "/v1/amb/messages"
tags: ["amb-messages"]
---

# List messages

`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`

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

## Query parameters

- `conversation_id` string
- `business_account_id` string
- `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.
- `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.
- `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.
- `category` string
- `tag` string[]
- `created_after` string, date-time
- `created_before` string, date-time
- `limit` integer
- `starting_after` string
- `ending_before` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Paginated list of messages.

- AMBMessageList (unresolved $ref)

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)