# API : Comptes Telegram, pools et stories

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

Un **compte Telegram** est un compte d’une créatrice, connecté à LanaChat via une connexion business (un bot qu’elle ajoute dans ses paramètres Telegram). Les comptes sont regroupés en **pools** : un pool correspond à une créatrice, un marché et une source de trafic, et les nouvelles conversations issues d’un lien de tracking sont réparties entre les comptes d’envoi du pool adéquat. Les **stories** sont publiées sur un ou plusieurs comptes simultanément.

## Endpoints

| Méthode | Chemin | Description | Permission | Statut |
|---|---|---|---|---|
| GET | `/accounts` | Liste des comptes (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Ajouter un compte avec son token de bot ; vérifié avec Telegram avant sauvegarde | `can_setup` | Planned |
| GET | `/accounts/{id}` | Un compte, son état et sa charge cette heure | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Modifier son brain, marché, trafic, alias ou langue de réponse ; l’activer ou le désactiver | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Déconnecter le compte (ses conversations sont conservées) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Tester la connexion immédiatement au lieu d’attendre la vérification horaire | `can_setup` | Planned |
| GET | `/pools` | Tous les pools avec leurs comptes, capacité et statut | `can_tracking` | Planned |
| GET | `/pools/settings` | Plafond horaire de l’espace de travail et règles de distribution | `can_tracking` | Planned |
| PUT | `/pools/settings` | Modifier le plafond horaire (100 à 100 000) et la distribution | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Ajouter ou retirer un compte du pool, le mettre en pause, définir son poids ou sa limite horaire | `can_tracking` | Planned |
| GET | `/pools/events` | Journal du pool : attentes flood, pauses, reprises, liens en attente | `can_tracking` | Planned |
| GET | `/stories` | Stories publiées et programmées (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Publier une story maintenant ou la programmer sur un ou plusieurs comptes | `can_setup` | Planned |
| GET | `/stories/{id}` | Une story avec ses vues, réactions et clics sur liens | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Annuler une story programmée | `can_setup` | Planned |

## L’objet compte

```json
{
  "id": "acc_1001",
  "creator_id": "cr_lea",
  "username": "lea_officiel",
  "bot_username": "lea_helper_bot",
  "health": "connected",
  "active": true,
  "brain_id": "br_lea_main",
  "pool_id": "pool_lea_fr_instagram",
  "market": "fr",
  "traffic": "instagram",
  "story_rights": true,
  "last_activity_at": "2026-10-06T13:58:20Z"
}
```

| Champ | Type | Description |
|---|---|---|
| `id` | string | Commence par `acc_` |
| `creator_id` | string | La créatrice à laquelle ce compte appartient |
| `username` | string | Le @username Telegram du compte, sans le @ |
| `bot_username` | string | Le bot lié via la connexion business |
| `health` | string | `connected`, `pending` ou `expired` |
| `active` | boolean | `false` quand le compte est désactivé : l’IA ne répond plus dessus |
| `brain_id` | string ou null | Le AI Brain qui répond sur ce compte |
| `pool_id` | string | Le pool dans lequel ses tags `market` et `traffic` le placent |
| `market` | string | Marché linguistique, par exemple `fr`, `en`, `pt-BR` ou `all` |
| `traffic` | string | Source de trafic, par exemple `instagram` ou `tiktok` |
| `story_rights` | boolean | Si la connexion business autorise LanaChat à publier des stories |
| `last_activity_at` | string | Dernier message envoyé ou reçu, ISO 8601 UTC |

- `health` est `connected`, `pending` (la connexion business n’est pas encore confirmée) ou `expired` (le bot a perdu l’accès ; reconnectez-le).
- Le token du bot n’est jamais retourné. LanaChat ne demande jamais de numéro de téléphone, mot de passe ou code 2FA.

## Comptes

### Lister les comptes

`GET /accounts` · `can_setup`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `creator_id` | string | Non | Seulement les comptes de cette créatrice |
| `health` | string | Non | `connected`, `pending` ou `expired` ; plusieurs séparés par des virgules |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/accounts?creator_id=cr_lea&health=connected,expired" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "acc_1001", "creator_id": "cr_lea", "username": "lea_officiel", "bot_username": "lea_helper_bot", "health": "connected", "active": true, "brain_id": "br_lea_main", "pool_id": "pool_lea_fr_instagram", "market": "fr", "traffic": "instagram", "story_rights": true, "last_activity_at": "2026-10-06T13:58:20Z" },
    { "id": "acc_1004", "creator_id": "cr_lea", "username": "lea_backup", "bot_username": "lea_helper2_bot", "health": "connected", "active": true, "brain_id": "br_lea_main", "pool_id": "pool_lea_fr_instagram", "market": "fr", "traffic": "instagram", "story_rights": false, "last_activity_at": "2026-10-06T13:51:02Z" }
  ],
  "next_cursor": null
}
```

### Ajouter un compte

`POST /accounts` · `can_setup`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `creator_id` | string | Oui | La créatrice à laquelle appartient le compte |
| `bot_token` | string | Oui | Le token du bot qu’elle a lié dans ses paramètres Telegram Business |
| `market` | string | Non | Marché linguistique, par exemple `fr` |
| `traffic` | string | Non | Source de trafic, par exemple `instagram` |

```bash
curl -X POST https://api.lanachat.ai/v1/accounts \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"creator_id": "cr_lea", "bot_token": "<bot token>", "market": "fr", "traffic": "instagram"}'
```

```json
{
  "id": "acc_1007",
  "creator_id": "cr_lea",
  "username": "lea_officiel",
  "bot_username": "lea_helper_bot",
  "health": "pending",
  "active": true,
  "brain_id": "br_lea_main",
  "pool_id": "pool_lea_fr_instagram",
  "market": "fr",
  "traffic": "instagram",
  "story_rights": false,
  "last_activity_at": null
}
```

La réponse est le compte (`201`) avec `health: "pending"` jusqu’à ce que la créatrice confirme la connexion business dans Telegram. Le token du bot est vérifié avec Telegram avant toute sauvegarde : un token refusé par Telegram répond `400`. Un compte déjà actif dans un autre workspace est refusé (`409`). Chaque compte nécessite une licence pour répondre : voir [Billing](https://lanachat.ai/guides/fr/api-billing/).

### Obtenir un compte

`GET /accounts/{id}` · `can_setup`

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

La réponse est l’objet compte, avec sa charge cette heure. Un id inconnu répond `404`.

### Mettre à jour un compte

`PATCH /accounts/{id}` · `can_setup`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `brain_id` | string | Non | Le brain qui répond sur ce compte |
| `market` | string | Non | Marché linguistique ; déplace le compte dans le pool correspondant |
| `traffic` | string | Non | Source de trafic ; déplace le compte dans le pool correspondant |
| `active` | boolean | Non | `false` désactive le compte, `true` le réactive |

L’alias et la langue de réponse du compte peuvent être modifiés de la même manière.

```bash
curl -X PATCH https://api.lanachat.ai/v1/accounts/acc_1004 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"traffic": "tiktok", "active": true}'
```

La réponse est le compte mis à jour. Désactiver le dernier compte d’envoi d’une créatrice ayant des liens actifs répond `409`.

### Déconnecter un compte

`DELETE /accounts/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/accounts/acc_1004 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Ses conversations sont conservées. Supprimer le dernier compte d’envoi d’une créatrice ayant des liens actifs répond `409`.

### Vérifier la connexion immédiatement

`POST /accounts/{id}/check` · `can_setup`

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

LanaChat vérifie chaque compte toutes les heures ; cet appel teste la connexion immédiatement. La réponse est le compte avec son `health` actualisé.

## Pools

Un pool est formé par les tags (`market` et `traffic`) de ses comptes ; il n’y a rien à créer. Une nouvelle conversation va dans le pool dont le trafic correspond à la source du lien et dont le marché correspond à la langue du fan, puis dans le pool "All traffic" de la créatrice, puis dans n’importe lequel de ses pools encore actif. Les conversations existantes restent toujours sur leur compte.

### Lister les pools

`GET /pools` · `can_tracking`

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

```json
{
  "data": [
    {
      "id": "pool_lea_fr_instagram",
      "name": "French · Instagram",
      "creator_id": "cr_lea",
      "accounts": ["acc_1001", "acc_1004"],
      "sent_last_hour": 312,
      "capacity_per_hour": 400,
      "status": "near"
    }
  ],
  "next_cursor": null
}
```

`status` est `sending`, `near` (80 % de sa capacité), `saturated` (95 %) ou `none` (pas de compte d’envoi).

### Obtenir les réglages du pool

`GET /pools/settings` · `can_tracking`

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

```json
{
  "cap_per_hour": 2000,
  "default_limit_per_hour": 200,
  "distribution": { "mode": "weighted", "warmup": true, "hold_when_saturated": true }
}
```

| Champ | Type | Description |
|---|---|---|
| `cap_per_hour` | number | Nombre de messages que tout l’espace de travail peut envoyer sur une heure glissante, 100 à 100 000 |
| `default_limit_per_hour` | number | Limite horaire donnée à un nouveau compte dans le pool |
| `distribution.mode` | string | `weighted` (aléatoire, proportionnel au poids de chaque compte), `round_robin` (chaque compte à son tour) ou `least_loaded` (le compte le plus éloigné de sa limite) |
| `distribution.warmup` | boolean | Un nouveau compte commence à 50 messages par heure et atteint sa limite complète au jour 7 |
| `distribution.hold_when_saturated` | boolean | Quand aucun compte ne peut prendre un nouveau fan, retenir le fan jusqu’à ce qu’un compte se libère, du plus ancien au plus récent ; sinon donner le fan au compte le moins chargé même au-delà de sa limite |

Quand l’espace de travail atteint `cap_per_hour`, les liens continuent de rediriger mais les nouvelles conversations sont retenues jusqu’à ce que l’heure glissante repasse sous le plafond.

### Modifier les réglages du pool

`PUT /pools/settings` · `can_tracking`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `cap_per_hour` | number | Oui | 100 à 100 000, entier |
| `default_limit_per_hour` | number | Oui | 10 à 1 000, entier |
| `distribution` | object | Oui | `mode`, `warmup` et `hold_when_saturated`, comme ci-dessus |

```bash
curl -X PUT https://api.lanachat.ai/v1/pools/settings \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cap_per_hour": 3000, "default_limit_per_hour": 200, "distribution": {"mode": "least_loaded", "warmup": true, "hold_when_saturated": true}}'
```

La réponse est les nouveaux réglages. Un plafond hors de 100 à 100 000 répond `400`.

### Modifier un compte dans le pool

`PATCH /pools/accounts/{account_id}` · `can_tracking`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `in_pool` | boolean | Non | `false` retire le compte du pool : il conserve ses conversations mais ne reçoit plus de nouveaux fans |
| `paused` | boolean | Non | `true` le met en pause dans le pool |
| `weight` | number | Non | 0 à 100 ; part des nouveaux fans en mode `weighted` (0 autorisé : pas de nouveau fan) |
| `limit_per_hour` | number | Non | 10 à 1 000 messages par heure pour ce compte |

```bash
curl -X PATCH https://api.lanachat.ai/v1/pools/accounts/acc_1004 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weight": 40, "limit_per_hour": 300}'
```

```json
{
  "account_id": "acc_1004",
  "creator_id": "cr_lea",
  "username": "lea_backup",
  "in_pool": true,
  "paused": false,
  "weight": 40,
  "limit_per_hour": 300,
  "sent_last_hour": 88,
  "new_conversations_today": 41,
  "state": "active",
  "flood_wait_until": null,
  "warmup_day": 7,
  "added_at": "2026-09-20T10:00:00Z"
}
```

- `state` est `active` ou `flood_wait` : en cas d’attente flood Telegram, le compte se met en pause jusqu’à `flood_wait_until`, puis reprend automatiquement.
- Pendant la montée en charge (`warmup_day` 1 à 7), le compte envoie moins que sa `limit_per_hour` : 50 messages à l’heure au jour 1, limite complète au jour 7.
- Retirer, mettre en pause ou supprimer le dernier compte d’envoi d’une créatrice ayant des liens actifs est refusé (`409`).

### Lire le journal du pool

`GET /pools/events` · `can_tracking`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `creator_id` | string | Non | Seulement les événements des comptes de cette créatrice |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/pools/events?creator_id=cr_lea&limit=2" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "at": "2026-10-06T13:40:12Z", "kind": "resumed", "creator_id": "cr_lea", "account_id": "acc_1004", "text": "@lea_backup is sending again." },
    { "at": "2026-10-06T13:25:12Z", "kind": "flood_wait", "creator_id": "cr_lea", "account_id": "acc_1004", "text": "@lea_backup hit a Telegram flood wait of 900 seconds." }
  ],
  "next_cursor": "eyJhdCI6IjIwMjYtMTAtMDZUMTM6MjU6MTJaIn0"
}
```

`kind` est `flood_wait`, `account_paused`, `resumed`, `link_paused` (le plafond workspace a été atteint, les nouveaux fans sont retenus), `account_added`, `account_removed` ou `settings`. `text` est une phrase en anglais simple.

## Stories

### Lister les stories

`GET /stories` · `can_setup`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `creator_id` | string | Non | Seulement les stories de cette créatrice |
| `status` | string | Non | Par exemple `scheduled` |
| `limit`, `cursor` | number, string | Non | [Pagination](https://lanachat.ai/guides/fr/api-overview/) |

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

```json
{
  "data": [ { "id": "sto_88", "status": "scheduled", "run_at": "2026-10-06T19:00:00Z", "account_ids": ["acc_1001", "acc_1004"] } ],
  "next_cursor": null
}
```

### Publier une story

`POST /stories` · `can_setup`

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `account_ids` | tableau de strings | Oui | Les comptes qui la publient |
| `media_id` | string | Oui | Une photo ou vidéo du [Vault](https://lanachat.ai/guides/fr/api-vault/) de la créatrice |
| `text` | string | Non | Légende |
| `link_id` | string | Non | Un [lien de tracking](https://lanachat.ai/guides/fr/api-tracking/) affiché sur la story |
| `duration_hours` | number | Non | Durée de visibilité de la story |
| `run_at` | string ou null | Non | Moment de publication (ISO 8601 UTC) ; omettez pour publier immédiatement |

```bash
curl -X POST https://api.lanachat.ai/v1/stories \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_ids": ["acc_1001", "acc_1004"], "media_id": "med_5521", "text": "New set tonight", "link_id": "lnk_3", "duration_hours": 24, "run_at": "2026-10-06T19:00:00Z"}'
```

```json
{ "id": "sto_88", "status": "scheduled", "run_at": "2026-10-06T19:00:00Z", "account_ids": ["acc_1001", "acc_1004"] }
```

Un compte sans le droit "manage stories" dans sa connexion business (`story_rights: false`) est refusé, avec la raison dans `message`.

### Obtenir une story

`GET /stories/{id}` · `can_setup`

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

La réponse est la story avec ses vues, réactions et clics sur liens une fois publiée.

### Annuler une story programmée

`DELETE /stories/{id}` · `can_setup`

```bash
curl -X DELETE https://api.lanachat.ai/v1/stories/sto_88 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Seule une story programmée peut être annulée.

## Articles liés

- [API LanaChat : démarrage rapide, authentification et erreurs](https://lanachat.ai/guides/fr/api-overview/)
- [Comptes Telegram : comptes, charge du pool et stories](https://lanachat.ai/guides/fr/telegram-accounts/)
- [Connecter des comptes Telegram (et ce qu’est une connexion business)](https://lanachat.ai/guides/fr/connect-telegram/)