# Conversations

> Read your inbox and the full transcript of a lead, page through messages and handle the personal data they contain.

Source: https://docs.whatsetter.com/developers/guides/conversations/

A conversation is the thread between your agent and one lead. The API gives you the inbox (leads with message activity) and the transcript of each lead, read-only.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/conversations`](/api-reference/operations/listconversations/) | `conversations:read` |
| GET | [`/conversations/{leadId}/messages`](/api-reference/operations/listconversationmessages/) | `conversations:read` |

## List conversations

The inbox: every lead that exchanged at least one message, most recent activity first.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/conversations?campaign_id=acme-france-1-ab12&limit=25" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/conversations?campaign_id=acme-france-1-ab12&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/conversations",
    params={"campaign_id": "acme-france-1-ab12", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
```

```json
{
  "data": [
    {
      "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "whatsapp_id": "33612345678@c.us",
      "name": "Julien",
      "status": "in_progress",
      "qualified": false,
      "replied": true,
      "campaign_id": "acme-france-1-ab12",
      "messages_count": 6,
      "last_message_at": "2026-09-18T16:42:05.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0d1" }
}
```

`campaign_id` accepts the campaign's slug or its `id`. Without it, conversations of group-purpose campaigns stay out, same as the dashboard. `last_message_direction: "inbound"` means the lead spoke last.

### Channels, who answers, what needs a reply

The inbox covers WhatsApp, Instagram and Messenger. Each conversation also says:

| Field | Meaning |
|---|---|
| `channel` | `whatsapp`, `instagram` or `facebook` (Messenger). On Instagram and Messenger `phone` and `whatsapp_id` are `null`. |
| `ig_username`, `account_id` | Instagram: the person's handle, and the account the thread lives on ([`GET /instagram/accounts`](/developers/guides/instagram/)). |
| `agent_active` | The agent answers this conversation now. `false` after a [handoff](/developers/guides/leads/), or while a person's reply pauses it (`agent_paused_until`). |
| `needs_reply` | A person owes it an answer: the dashboard's **To do** view. A message nobody answered (sent in the last 48 hours, unanswered after 30 minutes), or a next action overdue. |
| `triage_verdict` | Instagram and Messenger, when the agent answers every private message: what the triage (**What the agent leaves aside** in the dashboard) read the last message as. `collab` and `support` are left for you; `personal`, `spam`, `friend`, `no_text` and `blocked` get no reply. |

Filter with `channel=instagram`, `needs_reply=true` (only the conversations that need you) or `triage=collab`. To answer one, [`POST /messages`](/developers/guides/messages/#instagram-and-messenger).

## Read a lead's messages

`leadId` is the lead's `id` from `/leads` or `/conversations`. Messages come back newest first.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages?limit=50" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages?limit=50',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: messages, pagination } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/conversations/66f1a2b3c4d5e6f7a8b9c0d1/messages",
    params={"limit": 50},
    headers={"Authorization": "Bearer ws_live_…"},
)
messages = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e6",
      "direction": "inbound",
      "text": "Yes, 2pm works for me.",
      "type": "USER_MESSAGE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:42:05.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e5",
      "direction": "outbound",
      "text": "Are we still on for tomorrow at 2pm?",
      "type": "MANUAL_RESPONSE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:40:10.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0e5" }
}
```

| Field | Meaning |
|---|---|
| `direction` | `inbound` when the lead wrote, `outbound` when the agent, a teammate or the API wrote. |
| `text` | The message text, or `null` for a media-only message. |
| `type` | Internal interaction type, for example `USER_MESSAGE`, `AI_RESPONSE`, `LEAD_WELCOME`, `FOLLOWUP`, `MANUAL_RESPONSE`. Treat unknown values as opaque. |
| `variant` | The prompt variant that wrote the message, `A` to `D`: the first message prompt for a `LEAD_WELCOME`, the conversation prompt for an `AI_RESPONSE`. `null` on messages no prompt wrote. See [Agent prompts](/developers/guides/prompts/). |
| `has_media` | `true` when the message carried an image, voice note or document. The media itself is never linked. |
| `sent_at` | ISO 8601, UTC. |

## Pagination

Both endpoints return `pagination.has_more` and `pagination.next_cursor`. Pass `cursor=<next_cursor>` to get the next page; `limit` is 1 to 100, 25 by default. A cursor that points to a deleted row answers `422 validation_error` with "Invalid or expired cursor": restart from the first page.

To sync an inbox, poll `GET /conversations` and only fetch the transcript of leads whose `last_message_at` moved. For real-time, prefer [webhooks](/developers/webhooks/).

## Personal data

Transcripts contain phone numbers, names and whatever the person wrote. Treat them as personal data: store only what your use case needs, respect your retention policy, and never expose them to people who could not open the WhatSetter inbox. `phone` is digits only, without the `+`.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `conversations:read`. |
| 404 | `not_found` | Unknown lead, or a lead of another workspace. |
| 422 | `validation_error` | `limit` out of 1 to 100, invalid or expired cursor. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [Messages: reply to a lead](/developers/guides/messages/)
- [Leads](/developers/guides/leads/)
- [Conversations in the dashboard](/dashboard/conversations/)
- [Signed webhooks](/developers/webhooks/)
