API: Conturi Telegram, pool-uri și stories

Un cont Telegram este un cont al unei creatoare, conectat la LanaChat printr-o conexiune de business (un bot pe care îl adaugă în setările Telegram). Conturile sunt grupate în pool-uri: un pool este o creatoare, o piață și o sursă de trafic, iar conversațiile noi dintr-un link de tracking sunt distribuite între conturile de trimitere din pool-ul potrivit. Stories sunt postate simultan pe unul sau mai multe conturi.

Endpoints #

Obiectul contului #

{
  "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 poate fi connected, pending (conexiunea de business nu e confirmată încă) sau expired (botul a pierdut accesul; reconectează-l).
• Tokenul botului nu este niciodată returnat. LanaChat nu cere niciodată număr de telefon, parolă sau cod 2FA.

Conturi #

Listează conturile #

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
}

Adaugă un cont #

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
}

Răspunsul este contul (201) cu health: "pending" până când creatoarea confirmă conexiunea de business în Telegram. Tokenul botului este verificat cu Telegram înainte de salvare: un token refuzat de Telegram răspunde cu 400. Un cont deja activ în alt workspace este refuzat (409). Fiecare cont are nevoie de o licență pentru a răspunde: vezi Billing.

Obține un cont #

GET /accounts/{id} · can_setup

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

Răspunsul este obiectul contului, cu încărcarea lui în această oră. Un id necunoscut răspunde cu 404.

Actualizează un cont #

PATCH /accounts/{id} · can_setup

Aliasul și limba de răspuns pot fi schimbate la fel.

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

Răspunsul este contul actualizat. Oprirea ultimului cont de trimitere al unei creatoare cu linkuri active răspunde cu 409.

Deconectează un cont #

DELETE /accounts/{id} · can_setup

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

Conversațiile sunt păstrate. Eliminarea ultimului cont de trimitere al unei creatoare cu linkuri active răspunde cu 409.

Verifică conexiunea acum #

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 verifică fiecare cont o dată pe oră; acest apel îl testează imediat. Răspunsul este contul cu health actualizat.

Pool-uri #

Un pool este format din tag-urile conturilor sale (market și traffic); nu trebuie creat nimic. O conversație nouă merge în pool-ul al cărui trafic corespunde sursei linkului și piața corespunde limbii fanului, apoi în pool-ul "All traffic" al creatoarei, apoi în oricare din pool-urile ei care mai trimit. Conversațiile existente rămân întotdeauna pe contul lor.

Listează pool-urile #

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 poate fi sending, near (80% din capacitate), saturated (95%) sau none (fără cont de trimitere).

Obține setările pool-ului #

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

Când workspace-ul atinge cap_per_hour, linkurile continuă să redirecționeze, dar conversațiile noi sunt reținute până când ora scade sub limită.

Schimbă setările pool-ului #

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

Răspunsul sunt noile setări. O limită în afara intervalului 100-100.000 răspunde cu 400.

Schimbă un cont în 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 este active sau flood_wait: la o așteptare flood Telegram, contul se pune singur pe pauză până la flood_wait_until, apoi se reia automat.
• În perioada de încălzire (warmup_day 1 până la 7), contul trimite mai puțin decât limit_per_hour: 50 mesaje pe oră în ziua 1, limita completă în ziua 7.
• Scoaterea, pauzarea sau eliminarea ultimului cont de trimitere al unei creatoare cu linkuri active este refuzată (409).

Citește jurnalul pool-ului #

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 poate fi flood_wait, account_paused, resumed, link_paused (capacitatea workspace-ului a fost atinsă, fanii noi sunt reținuți), account_added, account_removed sau settings. text este o propoziție simplă în engleză.

Stories #

Listează 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
}

Postează o 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 cont fără dreptul "manage stories" în conexiunea de business (story_rights: false) este refuzat, cu motivul în message.

Obține o story #

GET /stories/{id} · can_setup

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

Răspunsul este story-ul cu vizualizările, reacțiile și click-urile pe link după ce este postată.

Anulează o story programată #

DELETE /stories/{id} · can_setup

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

Doar o story programată poate fi anulată.