API: Account Telegram, pool e stories

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 #

L’oggetto account #

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

• 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

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

{
  "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

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

{
  "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.

Ottieni un account #

GET /accounts/{id} · can_setup

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

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

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

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

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

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

{
  "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

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

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

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

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

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}'

{
  "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

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

{
  "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

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

{
  "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

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

{ "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

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

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

Si può annullare solo una story programmata.