# API : fans, conversations et messages

_API · Lecture de 7 min · Mis à jour 2026-10-22 · https://lanachat.ai/guides/fr/api-conversations/_

Un **fan** est un utilisateur Telegram qui a écrit à l’une de vos créatrices. Une **conversation** est le chat entre ce fan et un compte Telegram. Les messages sont envoyés par l’IA, par un membre de l’équipe ou par un script. Ces endpoints correspondent à **Live Convs** et **Fans** dans la Console.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/fans` | Lister les fans (`creator_id=`, `status=`, `list_id=`, `q=`, `spent_min=`) | `can_fan_read` | Planned |
| GET | `/fans/{id}` | Un fan : langues, dépenses, statut, listes, notes | `can_fan_read` | Planned |
| PATCH | `/fans/{id}` | Modifier l’alias, la langue de réponse ou les notes du fan | `can_chat` | Planned |
| GET | `/fans/{id}/sales` | Les achats du fan | `can_sales_read` | Planned |
| POST | `/fans/import` | Importer des fans et messages passés (n’envoie jamais rien) | `can_fan_import` | Planned |
| GET | `/fan-lists` | Listes (VIP, win back…) | `can_fan_read` | Planned |
| POST | `/fan-lists` | Créer une liste | `can_chat` | Planned |
| POST | `/fan-lists/{id}/members` | Ajouter des fans à une liste | `can_chat` | Planned |
| DELETE | `/fan-lists/{id}/members` | Retirer des fans d’une liste | `can_chat` | Planned |
| GET | `/conversations` | Lister les conversations (`creator_id=`, `account_id=`, `state=`, `unread=true`) | `can_fan_read` | Planned |
| GET | `/conversations/{id}` | Une conversation et qui répond | `can_fan_read` | Planned |
| GET | `/conversations/{id}/messages` | Messages, du plus récent au plus ancien (`translate=en` ajoute une traduction) | `can_fan_read` | Planned |
| POST | `/conversations/{id}/messages` | Envoyer un message en tant que créatrice (texte, média, offre) | `can_chat` | Planned |
| POST | `/conversations/{id}/reactions` | Ajouter ou retirer une réaction sur un message de fan | `can_chat` | Planned |
| POST | `/conversations/{id}/takeover` | Prendre la main : l’IA arrête de répondre à ce fan | `can_chat` | Planned |
| POST | `/conversations/{id}/release` | Redonner la conversation à l’IA | `can_chat` | Planned |
| POST | `/conversations/{id}/script` | Lancer un script sur cette conversation | `can_chat` | Planned |
| POST | `/conversations/{id}/read` | Marquer la conversation comme lue | `can_chat` | Planned |

## L’objet fan

```json
{
  "id": "fan_921",
  "display_name": "Marco",
  "username": "marco_dl",
  "creator_id": "cr_lea",
  "purchases": 9,
  "spent": { "stars": 1450, "net_cents": 1885 },
  "lists": ["vip"]
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Commence par `fan_` |
| `display_name` | string | Nom du fan sur Telegram |
| `username` | string or null | @username Telegram du fan, sans le @ |
| `creator_id` | string | La créatrice à qui ce fan a écrit |
| `purchases` | number | Achats vérifiés à ce jour |
| `spent` | object | Total dépensé : `stars`, et `net_cents` en cents US après la part Telegram et les remboursements |
| `lists` | array of strings | Ids des listes de fans auxquelles ce fan appartient |

Un fan contient aussi les langues utilisées, son tag de statut, les notes de l’équipe, un alias et une langue de réponse, comme sur la page **Fans**.

## L’objet conversation

```json
{
  "id": "conv_1001_88231",
  "fan_id": "fan_921",
  "creator_id": "cr_lea",
  "account_id": "acc_1001",
  "state": "ai",
  "status": { "tag": "active", "reason": null },
  "unread": 2,
  "last_message_at": "2026-10-06T14:02:51Z",
  "spent": { "stars": 1450, "net_cents": 1885 },
  "source_link_id": "lnk_3"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Commence par `conv_` |
| `fan_id`, `creator_id`, `account_id` | string | Qui parle à qui, sur quel compte Telegram |
| `state` | string | Qui répond : `ai`, `human` (prise en main), `script` (un script tourne) ou `off` |
| `status` | object | `tag` (tags de statut de la page Fans) et `reason` s’il y en a une |
| `unread` | number | Messages du fan non lus |
| `last_message_at` | string | ISO 8601, UTC |
| `spent` | object | Dépenses du fan dans cette conversation : `stars` et `net_cents` |
| `source_link_id` | string or null | Le lien de tracking d’où vient le fan |

`status.tag` correspond aux tags de statut de la page Fans (`review`, `safety_hold`, `converted`, `lost`, `underage`…). Une conversation en `off` pour raison de sécurité ne peut pas être rendue à l’IA (`409`).

## L’objet message

```json
{
  "id": "msg_77120",
  "from": "creator",
  "sent_by": "ai",
  "text": "Made this one this morning…",
  "media": [ { "id": "med_5521", "locked": true, "stars": 300 } ],
  "at": "2026-10-06T14:02:51Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Commence par `msg_` |
| `from` | string | `creator` ou `fan` |
| `sent_by` | string | Pour les messages de créatrice : `ai`, `human` ou `script` |
| `member_id` | string | Le membre de l’équipe qui l’a envoyé, si `sent_by` est `human` depuis la Console |
| `token_id` | string | Le token d’accès qui l’a envoyé, si cela vient de l’API |
| `text` | string | Texte du message |
| `media` | array | Médias envoyés : `id`, `locked` (payant et pas encore acheté) et prix en `stars` |
| `reactions` | array | Réactions sur un message de fan |
| `status` | string | Pour les messages envoyés : `queued`, `sent`, `read` ou `failed` |
| `at` | string | ISO 8601, UTC |

`sent_by` détermine la commission sur une vente, il est donc fixé côté serveur et jamais par votre requête.

## L’objet sale

```json
{
  "sale_id": "sale_8812",
  "fan_id": "fan_921",
  "creator_id": "cr_lea",
  "account_id": "acc_1001",
  "conversation_id": "conv_1001_88231",
  "stars": 300,
  "net_cents": 390,
  "sent_by": "ai",
  "kind": "offer"
}
```

| Field | Type | Description |
|---|---|---|
| `sale_id` | string | Commence par `sale_` |
| `fan_id`, `creator_id`, `account_id`, `conversation_id` | string | Qui a acheté, à qui, où |
| `stars` | number | Prix payé en Telegram Stars |
| `net_cents` | number | Valeur nette en cents US (un Star vaut $0.013) |
| `sent_by` | string | `ai`, `human` ou `script` : qui a envoyé l’offre, cela détermine la commission |
| `kind` | string | Ce qui a été acheté, par exemple `offer` |

Le même objet arrive par [webhook](https://lanachat.ai/guides/fr/api-webhooks/), événement `sale.completed`.

## Fans

### Lister les fans

`GET /fans` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Non | Seulement les fans de cette créatrice |
| `status` | string | Non | Un tag de statut de la page Fans, par exemple `converted` |
| `list_id` | string | Non | Seulement les fans de cette liste |
| `q` | string | Non | Partie du nom ou username du fan |
| `spent_min` | number | Non | Seulement les fans ayant dépensé au moins ce nombre de Stars |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/fans?creator_id=cr_lea&spent_min=1000&limit=50" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "fan_921", "display_name": "Marco", "username": "marco_dl", "creator_id": "cr_lea", "purchases": 9, "spent": { "stars": 1450, "net_cents": 1885 }, "lists": ["vip"] }
  ],
  "next_cursor": null
}
```

### Obtenir un fan

`GET /fans/{id}` · `can_fan_read`

```bash
curl https://api.lanachat.ai/v1/fans/fan_921 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La réponse est l’objet fan. Un id inconnu répond `404`.

### Mettre à jour un fan

`PATCH /fans/{id}` · `can_chat`

Envoyez uniquement ce qui change : alias, langue de réponse ou notes du fan. La réponse est le fan mis à jour.

```bash
curl -X PATCH https://api.lanachat.ai/v1/fans/fan_921 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Likes beach sets, buys at night"}'
```

### Lister les achats d’un fan

`GET /fans/{id}/sales` · `can_sales_read`

```bash
curl https://api.lanachat.ai/v1/fans/fan_921/sales \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "sale_id": "sale_8812", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001", "conversation_id": "conv_1001_88231", "stars": 300, "net_cents": 390, "sent_by": "ai", "kind": "offer" }
  ],
  "next_cursor": null
}
```

Une liste paginée d’objets sale. Pour les totaux par jour, lien ou source, utilisez [stats](https://lanachat.ai/guides/fr/api-tracking/).

### Importer l’historique des fans

`POST /fans/import` · `can_fan_import`

Ajoute des fans passés et leurs messages à vos données, par exemple depuis un autre outil. Cela n’envoie jamais de message à un fan et ne confirme jamais un achat.

```bash
curl -X POST https://api.lanachat.ai/v1/fans/import \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @fans-history.json
```

## Listes de fans

### Lister les listes de fans

`GET /fan-lists` · `can_fan_read`

```bash
curl https://api.lanachat.ai/v1/fan-lists \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [ { "id": "vip", "name": "VIP" } ],
  "next_cursor": null
}
```

### Créer une liste

`POST /fan-lists` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Oui | Le nom affiché sur la page Fans |

```bash
curl -X POST https://api.lanachat.ai/v1/fan-lists \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Win back"}'
```

La réponse est la nouvelle liste (`201`).

### Ajouter ou retirer des fans

`POST /fan-lists/{id}/members` et `DELETE /fan-lists/{id}/members` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fan_ids` | array of strings | Oui | Les fans à ajouter ou retirer |

```bash
curl -X POST https://api.lanachat.ai/v1/fan-lists/vip/members \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fan_ids": ["fan_921"]}'
```

`DELETE` prend le même body. Une liste ou un fan inconnu répond `404`.

## Conversations

### Lister les conversations

`GET /conversations` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Non | Seulement cette créatrice |
| `account_id` | string | Non | Seulement ce compte Telegram |
| `state` | string | Non | `ai`, `human`, `script` ou `off` |
| `unread` | boolean | Non | `true` : seulement les conversations avec des messages de fan non lus |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/conversations?creator_id=cr_lea&unread=true" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "conv_1001_88231", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001", "state": "ai", "status": { "tag": "active", "reason": null }, "unread": 2, "last_message_at": "2026-10-06T14:02:51Z", "spent": { "stars": 1450, "net_cents": 1885 }, "source_link_id": "lnk_3" }
  ],
  "next_cursor": null
}
```

### Obtenir une conversation

`GET /conversations/{id}` · `can_fan_read`

```bash
curl https://api.lanachat.ai/v1/conversations/conv_1001_88231 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La réponse est l’objet conversation ; `state` indique qui répond.

### Lire les messages

`GET /conversations/{id}/messages` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `translate` | string | Non | Un code langue, par exemple `en` : chaque message reçoit aussi une traduction |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/), du plus récent au plus ancien |

```bash
curl "https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages?limit=2" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "msg_77120", "from": "creator", "sent_by": "ai", "text": "Made this one this morning…", "media": [ { "id": "med_5521", "locked": true, "stars": 300 } ], "at": "2026-10-06T14:02:51Z" },
    { "id": "msg_77119", "from": "fan", "text": "show me more 😍", "reactions": [], "at": "2026-10-06T14:02:10Z" }
  ],
  "next_cursor": "eyJpZCI6Im1zZ183NzExOCJ9"
}
```

`sent_by` vaut `ai`, `human` (avec `member_id`) ou `script`.

### Envoyer un message

`POST /conversations/{id}/messages` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Oui, ou `media` | Le texte, en tant que créatrice |
| `media` | array | Non | Médias du Vault : `id`, et `stars` pour le vendre verrouillé à ce prix |
| `send_at` | string or null | Non | Heure ISO 8601 pour programmer l’envoi, jusqu’à 7 jours ; `null` envoie tout de suite |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text": "Only for you, tonight 🔥", "media": [{"id": "med_5522", "stars": 250}], "send_at": null}'
```

```json
{ "id": "msg_77121", "from": "creator", "sent_by": "human", "token_id": "tok_31", "status": "queued", "at": "2026-10-06T14:03:30Z" }
```

- Un message envoyé via l’API est considéré comme envoyé par une personne (`sent_by: "human"`, avec le token utilisé) et prend la main sur la conversation (`state: "human"`) jusqu’à ce que vous la rendiez.
- `status` passe par `queued`, `sent`, puis `read` ; `failed` contient la raison Telegram (par exemple flood wait).
- `send_at` programme le message (jusqu’à 7 jours à l’avance).

### Réagir à un message

`POST /conversations/{id}/reactions` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `message_id` | string | Oui | Le message du fan |
| `emoji` | string | Oui | La réaction |
| `on` | boolean | Oui | `true` l’ajoute, `false` la retire |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/reactions \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "msg_77119", "emoji": "❤️", "on": true}'
```

### Prendre la main

`POST /conversations/{id}/takeover` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/takeover \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "id": "conv_1001_88231", "state": "human", "taken_by": "tok_31", "taken_at": "2026-10-06T14:04:00Z" }
```

L’IA arrête de répondre à ce fan jusqu’à ce que vous rendiez la conversation.

### Redonner à l’IA

`POST /conversations/{id}/release` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/release \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

La réponse est la conversation avec `state: "ai"`. Une conversation en `off` pour raison de sécurité ne peut pas être rendue (`409`).

### Lancer un script

`POST /conversations/{id}/script` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `script_id` | string | Oui | Un script de la même créatrice, voir [Scripts](https://lanachat.ai/guides/fr/api-scripts/) |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/script \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"script_id": "scr_204"}'
```

Pendant l’exécution, le `state` de la conversation est `script`.

### Marquer comme lu

`POST /conversations/{id}/read` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/read \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Le `unread` de la conversation repasse à `0`.

## Articles liés

- [API LanaChat : démarrage rapide, authentification et erreurs](https://lanachat.ai/guides/fr/api-overview/)
- [Live Convs : lire, répondre et prendre le relais](https://lanachat.ai/guides/fr/live-convs/)
- [Fans : listes, statuts et VIP](https://lanachat.ai/guides/fr/fans/)