# List messages in a conversation

`GET /api/reporting/v1/conversations/{phone}/messages`  (operationId: `listMessages`, group: Reporting)

The thread. Every message says who sent it (customer, bot, agent or system), which team member if an agent, and its delivery status. Add expand=receipts to attach the time of each delivery and read tick to outbound messages.

Part of the full API, which is included in the Scale plan. Any one of these scopes is enough: `inbox`, `contacts`, `inbox:read`, `contacts:read`. Chat content: messages, names and phone numbers.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `phone` | path | string | yes | Contact phone number with the country code, digits only. A leading + is accepted. A 10-digit number with no country code is treated as Indian (91 is added). |
| `since` | query | string (date-time) | no | Only messages at or after this time. |
| `to` | query | string (date-time) | no | End of the window (ISO 8601 or date). Default: now. Alias: until. |
| `order` | query | string | no | asc: oldest first. desc: newest first. One of: `asc`, `desc`. Default asc. |
| `expand` | query | string | no | receipts: attach delivery and read times to outbound messages. One of: `receipts`. |
| `limit` | query | integer | no | Page size, 1 to 200. Default 100. Default 100. |
| `cursor` | query | string | no | The next_cursor from the previous page. Treat it as opaque. |

**Response 200**: OK (schema `MessageList`)

| Field | Type | Description |
| --- | --- | --- |
| `phone` | string |  |
| `data` | array of Message |  |
| `data[][].id` | integer | Internal row id (used by cursors). |
| `data[][].message_id` | string, nullable | WhatsApp message id (wamid). |
| `data[][].phone` | string | Contact phone number. |
| `data[][].sent_at` | string (date-time) | When the message was sent or received. |
| `data[][].sender_type` | string | customer: the contact. bot: the AI agent. agent: a team member (recorded on messages sent from InboxWA). system: any other outbound message (automation, campaign, template, or an older message with no recorded author). A bot reply is never reported as a human. One of: `customer`, `bot`, `agent`, `system`. |
| `data[][].actor` | object, nullable |  |
| `data[][].sender_label` | string, nullable | Display label recorded at send time. |
| `data[][].type` | string, nullable | text, template, image, audio, document and so on. |
| `data[][].text` | string, nullable | Message text. |
| `data[][].template_name` | string, nullable | Template name when a template was sent. |
| `data[][].media_url` | string, nullable | Media location, if any. |
| `data[][].status` | string, nullable | Inbound: unread or read. Outbound: sent, delivered, read or failed. |
| `data[][].source` | string, nullable | Channel, normally whatsapp. |
| `data[][].receipts` | array of Receipt | Only with expand=receipts, and only on outbound messages. |
| `data[][].receipts[][].status` | string | One of: `sent`, `delivered`, `read`, `failed`. |
| `data[][].receipts[][].at` | string (date-time) | When WhatsApp reported it. |
| `data[][].receipts[][].error` | string | Failure reason. |
| `next_cursor` | string, nullable |  |

Example:

```json
{
  "phone": "919876543210",
  "data": [
    {
      "id": 1041,
      "message_id": "wamid.HBgM...C1",
      "sent_at": "2026-10-02T09:00:00.000Z",
      "sender_type": "customer",
      "actor": null,
      "sender_label": null,
      "type": "text",
      "text": "My server is down",
      "template_name": null,
      "media_url": null,
      "status": "read",
      "source": "whatsapp"
    },
    {
      "id": 1044,
      "message_id": "wamid.HBgM...A1",
      "sent_at": "2026-10-02T09:05:12.000Z",
      "sender_type": "agent",
      "actor": {
        "user_id": 41,
        "name": "Anita"
      },
      "sender_label": "Anita",
      "type": "text",
      "text": "We are looking into it.",
      "template_name": null,
      "media_url": null,
      "status": "read",
      "source": "whatsapp",
      "receipts": [
        {
          "status": "sent",
          "at": "2026-10-02T09:05:12.000Z"
        },
        {
          "status": "delivered",
          "at": "2026-10-02T09:05:14.000Z"
        },
        {
          "status": "read",
          "at": "2026-10-02T09:05:50.000Z"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

**Errors specific to this call.** The common ones (401, 403, 429 and the rest) are in the [Errors guide](https://inboxwa.online/docs/api/guide/errors.md).

| Status | error | When |
| --- | --- | --- |
| 400 | `invalid_order` | order is not asc or desc. |

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json