# Conversations

> Lire ta boîte de réception et la transcription complète d'un lead, paginer les messages et traiter les données personnelles qu'ils contiennent.

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

Une conversation, c'est le fil entre ton agent et un lead. L'API te donne la boîte de réception (les leads avec de l'activité) et la transcription de chaque lead, en lecture seule.

## Endpoints

| Méthode | Chemin | Scope |
|---|---|---|
| GET | [`/conversations`](/api-reference/operations/listconversations/) | `conversations:read` |
| GET | [`/conversations/{leadId}/messages`](/api-reference/operations/listconversationmessages/) | `conversations:read` |

## Lister les conversations

La boîte de réception : chaque lead qui a échangé au moins un message, activité la plus récente d'abord.

**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` accepte le slug de la campagne ou son `id`. Sans lui, les conversations des campagnes de groupe restent à part, comme dans le dashboard. `last_message_direction: "inbound"` signifie que le lead a parlé en dernier.

### Canaux, qui répond, ce qui attend une réponse

La boîte de réception couvre WhatsApp, Instagram et Messenger. Chaque conversation dit aussi :

| Champ | Sens |
|---|---|
| `channel` | `whatsapp`, `instagram` ou `facebook` (Messenger). Sur Instagram et Messenger, `phone` et `whatsapp_id` valent `null`. |
| `ig_username`, `account_id` | Instagram : le pseudo de la personne, et le compte sur lequel vit le fil ([`GET /instagram/accounts`](/fr/developers/guides/instagram/)). |
| `agent_active` | L'agent répond à cette conversation en ce moment. `false` après une [prise en main](/fr/developers/guides/leads/), ou pendant qu'une réponse d'une personne le met en pause (`agent_paused_until`). |
| `needs_reply` | Une personne lui doit une réponse : le « À traiter » du dashboard. Un message resté sans réponse (envoyé dans les 48 dernières heures, sans réponse après 30 minutes), ou une prochaine action en retard. |
| `triage_verdict` | Instagram et Messenger, quand l'agent répond à tous les messages privés : ce que « Le tri » a lu dans le dernier message. `collab` et `support` te sont laissés ; `personal`, `spam`, `friend`, `no_text` et `blocked` ne reçoivent pas de réponse. |

Filtre avec `channel=instagram`, `needs_reply=true` (seulement les conversations qui t'attendent) ou `triage=collab`. Pour répondre, [`POST /messages`](/fr/developers/guides/messages/#instagram-et-messenger).

## Lire les messages d'un lead

`leadId` est l'`id` du lead venant de `/leads` ou `/conversations`. Les messages arrivent du plus récent au plus ancien.

**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": "Oui, 14h ça me va.",
      "type": "USER_MESSAGE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:42:05.000Z"
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e5",
      "direction": "outbound",
      "text": "On se confirme pour demain 14h ?",
      "type": "MANUAL_RESPONSE",
      "variant": null,
      "has_media": false,
      "sent_at": "2026-09-18T16:40:10.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0e5" }
}
```

| Champ | Signification |
|---|---|
| `direction` | `inbound` quand le lead a écrit, `outbound` quand l'agent, un coéquipier ou l'API a écrit. |
| `text` | Le texte du message, ou `null` pour un message qui ne contient qu'un média. |
| `type` | Type d'interaction interne, par exemple `USER_MESSAGE`, `AI_RESPONSE`, `LEAD_WELCOME`, `FOLLOWUP`, `MANUAL_RESPONSE`. Considère les valeurs inconnues comme opaques. |
| `variant` | La variante de prompt qui a écrit le message, de `A` à `D` : le prompt de premier message pour un `LEAD_WELCOME`, le prompt de conversation pour un `AI_RESPONSE`. `null` pour les messages qu'aucun prompt n'a écrits. Vois [Prompts des agents](/fr/developers/guides/prompts/). |
| `has_media` | `true` quand le message portait une image, un vocal ou un document. Le média lui-même n'est jamais lié. |
| `sent_at` | ISO 8601, UTC. |

## Pagination

Les deux endpoints renvoient `pagination.has_more` et `pagination.next_cursor`. Passe `cursor=<next_cursor>` pour la page suivante ; `limit` va de 1 à 100, 25 par défaut. Un curseur qui pointe vers une ligne supprimée répond `422 validation_error` avec « Invalid or expired cursor » : repars de la première page.

Pour synchroniser une boîte de réception, interroge `GET /conversations` et ne récupère la transcription que des leads dont `last_message_at` a bougé. Pour le temps réel, préfère les [webhooks](/fr/developers/webhooks/).

## Données personnelles

Les transcriptions contiennent des numéros de téléphone, des noms et tout ce que la personne a écrit. Traite-les comme des données personnelles : ne stocke que ce dont ton usage a besoin, respecte ta politique de conservation, et ne les montre jamais à quelqu'un qui ne pourrait pas ouvrir la boîte de réception WhatSetter. `phone` ne contient que des chiffres, sans le `+`.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 403 | `insufficient_scope` | La clé n'a pas `conversations:read`. |
| 404 | `not_found` | Lead inconnu, ou lead d'un autre espace de travail. |
| 422 | `validation_error` | `limit` hors de 1 à 100, curseur invalide ou expiré. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |

## Voir aussi

- [Messages : répondre à un lead](/fr/developers/guides/messages/)
- [Leads](/fr/developers/guides/leads/)
- [Conversations dans le dashboard](/fr/dashboard/conversations/)
- [Webhooks signés](/fr/developers/webhooks/)
