# List conversations

`GET /api/reporting/v1/conversations`  (operationId: `listConversations`, group: Reporting)

Chats active in the window, newest first, each with unread count, who spoke last, state, assignee and SLA deadline. Filters combine. The window defaults to the last 30 days so one call cannot scan a whole history; counts are measured inside it.

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 |
| --- | --- | --- | --- | --- |
| `unread` | query | boolean | no | Only chats with customer messages nobody has opened. |
| `needs_reply` | query | boolean | no | Only chats where the customer is waiting: they spoke last and no delivered reply followed. Failed sends do not count as replies. |
| `state` | query | string | no | Only chats in this state. One of: `AI_ONLY`, `HANDOFF_PENDING`, `HUMAN_ACTIVE`. |
| `assigned_to` | query | integer | no | Only chats assigned to this team member (user id). |
| `sla_breached` | query | boolean | no | Only chats waiting for a person past their SLA deadline. |
| `q` | query | string | no | Search contact name or phone number. |
| `since` | query | string (date-time) | no | Start of the window: an ISO 8601 timestamp or a date (YYYY-MM-DD, start of that UTC day). Default: 30 days ago. Alias: from. |
| `to` | query | string (date-time) | no | End of the window (ISO 8601 or date). Default: now. Alias: until. |
| `sort` | query | string | no | last_activity: newest first. waiting_longest: customers who have waited longest first. One of: `last_activity`, `waiting_longest`. Default last_activity. |
| `limit` | query | integer | no | Page size, 1 to 200. Default 50. Default 50. |
| `cursor` | query | string | no | The next_cursor from the previous page. Treat it as opaque. |

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

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of ConversationSummary |  |
| `data[][].phone` | string | Contact phone number, digits only, as stored. |
| `data[][].contact_name` | string, nullable | Contact name if known. |
| `data[][].state` | string | AI_ONLY: the bot is handling it. HANDOFF_PENDING: waiting for a person. HUMAN_ACTIVE: a person has it. One of: `AI_ONLY`, `HANDOFF_PENDING`, `HUMAN_ACTIVE`. |
| `data[][].handover_reason` | string, nullable | Why it was handed to a person. |
| `data[][].assigned_to` | object, nullable |  |
| `data[][].claimed_by` | object, nullable |  |
| `data[][].unread_count` | integer | Customer messages nobody has opened, inside the window. |
| `data[][].needs_reply` | boolean | The customer spoke last (or, when the workspace has the unattended-AI-reply setting, the AI did) and no delivered reply has followed. |
| `data[][].last_message` | object, nullable |  |
| `data[][].last_message.message_id` | string, nullable | WhatsApp message id. |
| `data[][].last_message.sender_type` | string, nullable | 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[][].last_message.sent_at` | string (date-time) | When it was sent. |
| `data[][].last_message.preview` | string, nullable | First 140 characters. |
| `data[][].waiting_since` | string (date-time), nullable | When the customer began waiting. Null unless needs_reply. |
| `data[][].waiting_seconds` | integer, nullable | Seconds the customer has been waiting. |
| `data[][].sla_deadline_at` | string (date-time), nullable | SLA response deadline, if a policy applies. |
| `data[][].sla_breached` | boolean | Deadline passed while still waiting for a person. |
| `data[][].labels` | array of string |  |
| `data[][].counts` | object |  |
| `data[][].counts.messages` | integer |  |
| `data[][].counts.from_customer` | integer |  |
| `data[][].counts.from_bot` | integer |  |
| `next_cursor` | string, nullable | Pass as cursor to get the next page. Null on the last page. |
| `window` | Window |  |
| `window.from` | string (date-time) | Start of the window. |
| `window.to` | string (date-time) | End of the window. |

Example:

```json
{
  "data": [
    {
      "phone": "919876543210",
      "contact_name": "Ravi Kumar",
      "state": "HUMAN_ACTIVE",
      "handover_reason": "human_claimed",
      "assigned_to": {
        "user_id": 41,
        "name": "Anita"
      },
      "claimed_by": {
        "user_id": 41,
        "name": "Anita"
      },
      "unread_count": 3,
      "needs_reply": true,
      "last_message": {
        "message_id": "wamid.HBgM...C3",
        "sender_type": "customer",
        "sent_at": "2026-10-02T09:06:40.000Z",
        "preview": "Server is still down, please check"
      },
      "waiting_since": "2026-10-02T09:06:40.000Z",
      "waiting_seconds": 1260,
      "sla_deadline_at": null,
      "sla_breached": false,
      "labels": [
        "vip"
      ],
      "counts": {
        "messages": 5,
        "from_customer": 3,
        "from_bot": 1
      }
    }
  ],
  "next_cursor": "eyJrIjoidHMiLCJ0cyI6IjIwMjYtMTAtMDJUMDk6MDY6NDAuMDAwWiIsInBob25lIjoiOTE5ODc2NTQzMjEwIn0",
  "window": {
    "from": "2026-09-02T00:00:00.000Z",
    "to": "2026-10-02T09:30:00.000Z"
  }
}
```

**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_state` | state is not one of the three states. |
| 400 | `invalid_assigned_to` | assigned_to is not a user id. |
| 400 | `invalid_sort` | sort is not recognised. |
| 400 | `invalid_since` | since or to is not a date. |
| 400 | `window_too_large` | The window is longer than 400 days. |

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