> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sayvyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List messages

> Retrieve paginated messages across the organization or optionally filtered by ticket ID

Query historical messages sent and received across your organization's messaging channels. Can be filtered by `inbox_id` to fetch thread history, and ordered chronologically (`asc` or `desc`).

***

### Authentication

This endpoint requires Bearer token authentication.

```http theme={null}
Authorization: Bearer <token>
```

| Header          | Type     | Required | Description                                     | Format           |
| :-------------- | :------- | :------- | :---------------------------------------------- | :--------------- |
| `Authorization` | `string` | **Yes**  | Scoped organization API key or Bearer JWT token | `Bearer <token>` |

***

### Query Parameters

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField query="inbox_id" type="string">
  Filter messages belonging to a specific conversation ticket UUID.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of messages to retrieve (1 to 100).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of items to skip for pagination (minimum `0`).
</ParamField>

<ParamField query="order" type="string" default="desc">
  Chronological sort order by `created_at`. Allowed values: `asc`, `desc`.
</ParamField>

***

### Response Fields

<ResponseField name="total" type="integer">
  Total count of matching messages.
</ResponseField>

<ResponseField name="page" type="integer">
  Computed page index.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items returned in this page.
</ResponseField>

<ResponseField name="messages" type="object[]">
  Array of message objects.

  <Expandable title="MessageResponse Fields">
    <ResponseField name="id" type="string">
      UUID identifier of the message.
    </ResponseField>

    <ResponseField name="inbox_id" type="string">
      UUID of the parent inbox ticket.
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      UUID of the organization.
    </ResponseField>

    <ResponseField name="contact_id" type="string">
      UUID of the contact participating in the thread.
    </ResponseField>

    <ResponseField name="whatsapp_message_id" type="string">
      Meta WhatsApp message identifier (`wamid.HBg...`), or `null`.
    </ResponseField>

    <ResponseField name="direction" type="string">
      Message direction: `inbound` (from customer) or `outbound` (from agent/bot).
    </ResponseField>

    <ResponseField name="message_type" type="string">
      Type of message payload (`text`, `image`, `document`, `audio`, `video`).
    </ResponseField>

    <ResponseField name="body" type="string">
      Text body, message transcript, or media caption.
    </ResponseField>

    <ResponseField name="status" type="string">
      Delivery status (`sent`, `delivered`, `read`, `failed`).
    </ResponseField>

    <ResponseField name="media_url" type="string">
      Relative API streaming URL or remote media key (e.g. `/api/v1/inbox/media/{message_id}`).
    </ResponseField>

    <ResponseField name="media_mime_type" type="string">
      MIME type of attached file (e.g. `image/png`, `application/pdf`).
    </ResponseField>

    <ResponseField name="media_filename" type="string">
      Original filename of attachment.
    </ResponseField>

    <ResponseField name="context_message_id" type="string">
      WhatsApp wamid of the parent message if this was a reply.
    </ResponseField>

    <ResponseField name="reactions" type="object">
      Dictionary of sender phone numbers and active emoji reactions.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 last update timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.sayvy.ai/api/v1/inbox/messages?limit=20&order=desc" \
    -H "Authorization: Bearer <token>"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.sayvy.ai/api/v1/inbox/messages"
  headers = {
      "Authorization": "Bearer <token>"
  }
  params = {
      "limit": 20,
      "order": "desc"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.status_code)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sayvy.ai/api/v1/inbox/messages?limit=20&order=desc", {
    method: "GET",
    headers: {
      "Authorization": "Bearer <token>"
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "total": 54,
    "page": 1,
    "size": 20,
    "messages": [
      {
        "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
        "inbox_id": "e4f3a2b1-9c8d-7e6f-5a4b-3c2d1e0f9a8b",
        "organization_id": "e0b973dc-13a8-4c9f-861a-03e5b4b1a8d9",
        "contact_id": "8a7c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "whatsapp_message_id": "wamid.HBgLMTE4OTAwOTk5MTE1FQIAERgSRjQ1Q0IzOTk3RTYwRTczMzNCAA==",
        "direction": "outbound",
        "message_type": "text",
        "body": "Hello Sarah, your enterprise demonstration has been scheduled for tomorrow at 2 PM.",
        "status": "read",
        "media_url": null,
        "media_mime_type": null,
        "media_filename": null,
        "context_message_id": null,
        "reactions": {
          "+14155552671": "👍"
        },
        "created_at": "2026-09-07T15:32:00Z",
        "updated_at": "2026-09-07T15:33:10Z"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": "Order must be either 'asc' or 'desc'"
  }
  ```
</ResponseExample>