# API: Account Telegram, pool e stories

_API · 8 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-telegram-accounts/_

Un **account Telegram** è un account di una creator, collegato a LanaChat tramite una connessione business (un bot che aggiunge nelle sue impostazioni Telegram). Gli account sono raggruppati in **pool**: un pool è una creator, un mercato e una fonte di traffico, e le nuove conversazioni da un link di tracciamento vengono distribuite tra gli account invianti del pool corretto. Le **stories** vengono pubblicate su uno o più account contemporaneamente.

## Endpoint

| Method | Path | Descrizione | Permesso | Stato |
|---|---|---|---|---|
| GET | `/accounts` | Elenca gli account (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Aggiunge un account con il suo token bot; verificato con Telegram prima di salvarlo | `can_setup` | Planned |
| GET | `/accounts/{id}` | Un account, il suo stato e il suo carico in quest’ora | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Cambia brain, mercato, traffico, alias o lingua di risposta; attiva o disattiva | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Disconnette l’account (le conversazioni restano) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Testa la connessione ora invece di aspettare il controllo orario | `can_setup` | Planned |
| GET | `/pools` | Tutti i pool con i loro account, capacità e stato | `can_tracking` | Planned |
| GET | `/pools/settings` | Limite orario del workspace e regole di distribuzione | `can_tracking` | Planned |
| PUT | `/pools/settings` | Cambia il limite orario (100 a 100.000) e la distribuzione | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Inserisce o esclude un account dal pool, lo mette in pausa, imposta peso o limite orario | `can_tracking` | Planned |
| GET | `/pools/events` | Log del pool: attese flood, pause, riprese, link trattenuti | `can_tracking` | Planned |
| GET | `/stories` | Stories pubblicate e programmate (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Pubblica una story ora o la programma su uno o più account | `can_setup` | Planned |
| GET | `/stories/{id}` | Una story con visualizzazioni, reazioni e click sui link | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Annulla una story programmata | `can_setup` | Planned |

## L’oggetto account

```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"
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Inizia con `acc_` |
| `creator_id` | string | La creator a cui appartiene l’account |
| `username` | string | L’@username Telegram dell’account, senza la @ |
| `bot_username` | string | Il bot collegato tramite la connessione business |
| `health` | string | `connected`, `pending` o `expired` |
| `active` | boolean | `false` quando l’account è spento: l’AI non risponde |
| `brain_id` | string o null | L’AI Brain che risponde su questo account |
| `pool_id` | string | Il pool in cui lo mettono i tag `market` e `traffic` |
| `market` | string | Mercato linguistico, es. `fr`, `en`, `pt-BR` o `all` |
| `traffic` | string | Fonte di traffico, es. `instagram` o `tiktok` |
| `story_rights` | boolean | Se la connessione business permette a LanaChat di pubblicare stories |
| `last_activity_at` | string | Ultimo messaggio inviato o ricevuto, ISO 8601 UTC |

- `health` può essere `connected`, `pending` (connessione business non ancora confermata) o `expired` (il bot ha perso accesso; riconnetterlo).
- Il token bot non viene mai restituito. LanaChat non chiede mai numero di telefono, password o codice 2FA.

## Account

### Elenca gli account

`GET /accounts` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | No | Solo gli account di questa creator |
| `health` | string | No | `connected`, `pending` o `expired`; più valori separati da virgola |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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
}
```

### Aggiungi un account

`POST /accounts` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | Sì | La creator a cui appartiene l’account |
| `bot_token` | string | Sì | Il token del bot collegato nelle impostazioni Telegram Business |
| `market` | string | No | Mercato linguistico, es. `fr` |
| `traffic` | string | No | Fonte di traffico, es. `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 risposta è l’account (`201`) con `health: "pending"` finché la creator non conferma la connessione business su Telegram. Il token bot viene verificato con Telegram prima di salvare: un token rifiutato da Telegram risponde `400`. Un account già attivo in un altro workspace è rifiutato (`409`). Ogni account necessita di una licenza per rispondere: vedi [Billing](https://lanachat.ai/guides/it/api-billing/).

### Ottieni un account

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

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

La risposta è l’oggetto account, con il suo carico in quest’ora. Un id sconosciuto risponde `404`.

### Aggiorna un account

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `brain_id` | string | No | Il brain che risponde su questo account |
| `market` | string | No | Mercato linguistico; sposta l’account nel pool corrispondente |
| `traffic` | string | No | Fonte di traffico; sposta l’account nel pool corrispondente |
| `active` | boolean | No | `false` spegne l’account, `true` lo riaccende |

Alias e lingua di risposta dell’account si possono cambiare allo stesso modo.

```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 risposta è l’account aggiornato. Spegnere l’ultimo account inviato di una creator con link attivi risponde `409`.

### Disconnetti un account

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

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

Le conversazioni restano. Rimuovere l’ultimo account inviato di una creator con link attivi risponde `409`.

### Verifica la connessione ora

`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 controlla ogni account ogni ora; questa chiamata lo testa subito. La risposta è l’account con il suo `health` aggiornato.

## Pool

Un pool è formato dai tag dei suoi account (`market` e `traffic`); non si crea nulla. Una nuova conversazione va al pool il cui traffico corrisponde alla fonte del link e il cui mercato corrisponde alla lingua del fan, poi al pool "All traffic" della creator, poi a qualsiasi suo pool che invii ancora. Le conversazioni esistenti restano sempre sul loro account.

### Elenca i pool

`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` può essere `sending`, `near` (80% della capacità), `saturated` (95%) o `none` (nessun account inviato).

### Ottieni le impostazioni del 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 }
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `cap_per_hour` | number | Messaggi che tutto il workspace può inviare in un’ora mobile, da 100 a 100.000 |
| `default_limit_per_hour` | number | Limite orario assegnato a un nuovo account nel pool |
| `distribution.mode` | string | `weighted` (random proporzionale al peso di ogni account), `round_robin` (a turno) o `least_loaded` (account più lontano dal limite) |
| `distribution.warmup` | boolean | Un nuovo account parte da 50 messaggi/ora e raggiunge il limite pieno al giorno 7 |
| `distribution.hold_when_saturated` | boolean | Se nessun account può prendere un nuovo fan, trattieni il fan finché uno non si libera, dal più vecchio; altrimenti dai il fan all’account meno carico anche oltre il limite |

Quando il workspace raggiunge `cap_per_hour`, i link continuano a reindirizzare ma le nuove conversazioni sono trattenute finché l’ora scende sotto il limite.

### Cambia le impostazioni del pool

`PUT /pools/settings` · `can_tracking`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `cap_per_hour` | number | Sì | Da 100 a 100.000, numero intero |
| `default_limit_per_hour` | number | Sì | Da 10 a 1.000, numero intero |
| `distribution` | object | Sì | `mode`, `warmup` e `hold_when_saturated`, come sopra |

```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 risposta sono le nuove impostazioni. Un limite fuori da 100 a 100.000 risponde `400`.

### Cambia un account nel pool

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

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `in_pool` | boolean | No | `false` esclude l’account dal pool: mantiene le conversazioni ma non riceve nuovi fan |
| `paused` | boolean | No | `true` lo mette in pausa nel pool |
| `weight` | number | No | Da 0 a 100; quota di nuovi fan in modalità `weighted` (0 significa nessun nuovo fan) |
| `limit_per_hour` | number | No | Da 10 a 1.000 messaggi all’ora per questo account |

```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` è `active` o `flood_wait`: in caso di flood wait Telegram l’account si mette in pausa fino a `flood_wait_until`, poi riprende da solo.
- Durante il warm-up (`warmup_day` da 1 a 7) l’account invia meno del suo `limit_per_hour`: 50 messaggi all’ora al giorno 1, limite pieno al giorno 7.
- Escludere, mettere in pausa o rimuovere l’ultimo account inviato di una creator con link attivi è rifiutato (`409`).

### Leggi il log del pool

`GET /pools/events` · `can_tracking`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | No | Solo eventi degli account di questa creator |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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` può essere `flood_wait`, `account_paused`, `resumed`, `link_paused` (limite workspace raggiunto, nuovi fan trattenuti), `account_added`, `account_removed` o `settings`. `text` è una frase in inglese semplice.

## Stories

### Elenca le stories

`GET /stories` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `creator_id` | string | No | Solo le stories di questa creator |
| `status` | string | No | Per esempio `scheduled` |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/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
}
```

### Pubblica una story

`POST /stories` · `can_setup`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `account_ids` | array di stringhe | Sì | Gli account che la pubblicano |
| `media_id` | string | Sì | Una foto o video della [Vault](https://lanachat.ai/guides/it/api-vault/) della creator |
| `text` | string | No | Didascalia |
| `link_id` | string | No | Un [tracking link](https://lanachat.ai/guides/it/api-tracking/) mostrato nella story |
| `duration_hours` | number | No | Quanto dura la story |
| `run_at` | string o null | No | Quando pubblicarla (ISO 8601 UTC); omettere per pubblicare ora |

```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 account senza il diritto "manage stories" nella sua connessione business (`story_rights: false`) è rifiutato, con la ragione in `message`.

### Ottieni una story

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

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

La risposta è la story con visualizzazioni, reazioni e click sui link una volta pubblicata.

### Annulla una story programmata

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

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

Si può annullare solo una story programmata.

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Account Telegram: account, carico del pool e storie](https://lanachat.ai/guides/it/telegram-accounts/)
- [Collega gli account Telegram (e cos'è una connessione business)](https://lanachat.ai/guides/it/connect-telegram/)