# List conversations (inbox)

`GET https://app.whatsetter.com/api/v1/conversations`

Leads with message activity, most recent first (your WhatSetter inbox),
on WhatsApp, Instagram and Messenger. Each one says its `channel`,
whether the agent answers it now (`agent_active`; a person's reply
pauses it until `agent_paused_until`), whether a person owes it an
answer (`needs_reply`: the dashboard's « To do » view, a message nobody
answered within 48 hours or a next action overdue) and, on Instagram
and Messenger, what the triage (« What the agent leaves aside » in the dashboard) read the last message as
(`triage_verdict`).

Like `GET /leads`, participants of group-purpose campaigns are left out
unless you filter on that `campaign_id`. Requires scope
`conversations:read`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `campaign_id` | query | string | no | Filter by campaign. Accepts the campaign's `campaign_id` slug or its document `id` (both returned by `GET /campaigns`). |
| `channel` | query | whatsapp \| instagram \| facebook | no | One channel. `whatsapp` also returns the conversations from before the channel was recorded. |
| `needs_reply` | query | true | no | `true`: only the conversations a person owes an answer (the dashboard's « To do » view). Leave it out for every conversation. |
| `triage` | query | prospect \| collab \| support \| personal \| spam \| friend \| no_text \| blocked \| unread | no | Instagram and Messenger: only the conversations whose last message the triage read this way. `collab` and `support` are left for the owner; `personal`, `spam`, `friend`, `no_text` and `blocked` get no reply. |
| `limit` | query | integer | no |  |
| `cursor` | query | string | no | Opaque cursor from the previous page's `pagination.next_cursor`. |

## Example request

```bash
curl --request GET \
  --url 'https://app.whatsetter.com/api/v1/conversations' \
  --header 'Authorization: Bearer ws_live_…'
```

## Responses

### 200: Page of conversation summaries

```json
{
  "data": [
    {
      "lead_id": "",
      "channel": "whatsapp",
      "phone": "",
      "whatsapp_id": "",
      "ig_username": "",
      "account_id": "",
      "name": "",
      "status": "",
      "qualified": false,
      "replied": false,
      "campaign_id": "",
      "agent_active": false,
      "agent_paused_until": "",
      "needs_reply": false,
      "triage_verdict": "prospect",
      "messages_count": 0,
      "last_message_at": "",
      "last_message_direction": ""
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: The key lacks the required scope (`insufficient_scope`), the plan does not have this part of the API (`not_in_plan`), or Instagram is not enabled on the workspace (`instagram_not_enabled`, Instagram routes)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/listconversations/
