# API: Conturi Telegram, pool-uri și stories

_API · 8 min de citit · Actualizat 2026-10-22 · https://lanachat.ai/guides/ro/api-telegram-accounts/_

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

| Method | Path | Descriere | Permisiune | Stare |
|---|---|---|---|---|
| GET | `/accounts` | Listează conturile (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Adaugă un cont cu tokenul botului; verificat cu Telegram înainte de salvare | `can_setup` | Planned |
| GET | `/accounts/{id}` | Un cont, starea lui și încărcarea în această oră | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Schimbă brain-ul, piața, traficul, aliasul sau limba de răspuns; activează sau dezactivează | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Deconectează contul (conversațiile se păstrează) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Testează conexiunea acum, fără să aștepte verificarea orară | `can_setup` | Planned |
| GET | `/pools` | Toate pool-urile cu conturile, capacitatea și starea lor | `can_tracking` | Planned |
| GET | `/pools/settings` | Limita orară a workspace-ului și regulile de distribuție | `can_tracking` | Planned |
| PUT | `/pools/settings` | Schimbă limita orară (100 până la 100.000) și distribuția | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Scoate sau adaugă un cont în pool, îl pune pe pauză, setează greutatea sau limita orară | `can_tracking` | Planned |
| GET | `/pools/events` | Jurnalul pool-ului: așteptări flood, pauze, reluări, linkuri reținute | `can_tracking` | Planned |
| GET | `/stories` | Stories postate și programate (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Postează o story acum sau o programează pe unul sau mai multe conturi | `can_setup` | Planned |
| GET | `/stories/{id}` | O story cu vizualizările, reacțiile și click-urile pe link | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Anulează o story programată | `can_setup` | Planned |

## Obiectul contului

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

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Începe cu `acc_` |
| `creator_id` | string | Creatoarea căreia îi aparține contul |
| `username` | string | Telegram @username al contului, fără @ |
| `bot_username` | string | Botul legat prin conexiunea de business |
| `health` | string | `connected`, `pending` sau `expired` |
| `active` | boolean | `false` când contul este oprit: AI-ul nu răspunde pe el |
| `brain_id` | string sau null | AI Brain care răspunde pe acest cont |
| `pool_id` | string | Pool-ul în care îl plasează tag-urile `market` și `traffic` |
| `market` | string | Piața de limbă, de exemplu `fr`, `en`, `pt-BR` sau `all` |
| `traffic` | string | Sursa de trafic, de exemplu `instagram` sau `tiktok` |
| `story_rights` | boolean | Dacă conexiunea de business permite LanaChat să posteze stories |
| `last_activity_at` | string | Ultimul mesaj trimis sau primit, ISO 8601 UTC |

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `creator_id` | string | Nu | Doar conturile acestei creatoare |
| `health` | string | Nu | `connected`, `pending` sau `expired`; mai multe separate prin virgulă |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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
}
```

### Adaugă un cont

`POST /accounts` · `can_setup`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `creator_id` | string | Da | Creatoarea căreia îi aparține contul |
| `bot_token` | string | Da | Tokenul botului legat în setările Business Telegram |
| `market` | string | Nu | Piața de limbă, de exemplu `fr` |
| `traffic` | string | Nu | Sursa de trafic, de exemplu `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
}
```

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](https://lanachat.ai/guides/ro/api-billing/).

### Obține un cont

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

```bash
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`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `brain_id` | string | Nu | Brain-ul care răspunde pe acest cont |
| `market` | string | Nu | Piața de limbă; mută contul în pool-ul corespunzător |
| `traffic` | string | Nu | Sursa de trafic; mută contul în pool-ul corespunzător |
| `active` | boolean | Nu | `false` oprește contul, `true` îl reactivează |

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

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

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`

```bash
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`

```bash
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`

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

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

| Câmp | Tip | Descriere |
|---|---|---|
| `cap_per_hour` | number | Mesaje pe care întreg workspace-ul le poate trimite într-o oră rulantă, 100 până la 100.000 |
| `default_limit_per_hour` | number | Limită orară dată unui cont nou în pool |
| `distribution.mode` | string | `weighted` (aleator, proporțional cu greutatea fiecărui cont), `round_robin` (fiecare cont pe rând) sau `least_loaded` (contul cel mai departe de limită) |
| `distribution.warmup` | boolean | Un cont nou începe cu 50 mesaje pe oră și ajunge la limita completă în ziua 7 |
| `distribution.hold_when_saturated` | boolean | Când niciun cont nu poate prelua un fan nou, îl ține în așteptare până se eliberează unul, cel mai vechi primul; altfel dă fanul contului cel mai puțin încărcat chiar dacă depășește limita |

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`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `cap_per_hour` | number | Da | 100 până la 100.000, număr întreg |
| `default_limit_per_hour` | number | Da | 10 până la 1.000, număr întreg |
| `distribution` | object | Da | `mode`, `warmup` și `hold_when_saturated`, ca mai sus |

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

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`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `in_pool` | boolean | Nu | `false` scoate contul din pool: păstrează conversațiile, dar nu primește fani noi |
| `paused` | boolean | Nu | `true` îl pune pe pauză în pool |
| `weight` | number | Nu | 0 până la 100; ponderea fanilor noi în modul `weighted` (0 înseamnă fără fani noi) |
| `limit_per_hour` | number | Nu | 10 până la 1.000 mesaje pe oră pentru acest cont |

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

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `creator_id` | string | Nu | Doar evenimentele conturilor acestei creatoare |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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` 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`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `creator_id` | string | Nu | Doar stories ale acestei creatoare |
| `status` | string | Nu | De exemplu `scheduled` |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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
}
```

### Postează o story

`POST /stories` · `can_setup`

| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `account_ids` | array de stringuri | Da | Conturile care o postează |
| `media_id` | string | Da | O fotografie sau video din [Vault](https://lanachat.ai/guides/ro/api-vault/) al creatoarei |
| `text` | string | Nu | Textul de sub poză |
| `link_id` | string | Nu | Un [link de tracking](https://lanachat.ai/guides/ro/api-tracking/) afișat în story |
| `duration_hours` | number | Nu | Cât timp rămâne story-ul activ |
| `run_at` | string sau null | Nu | Când să fie postată (ISO 8601 UTC); omite pentru postare imediată |

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

```bash
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`

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

Doar o story programată poate fi anulată.

## Articole conexe

- [API LanaChat: început rapid, autentificare și erori](https://lanachat.ai/guides/ro/api-overview/)
- [Conturi Telegram: conturi, încărcarea pool-ului și stories](https://lanachat.ai/guides/ro/telegram-accounts/)
- [Conectează conturile Telegram (și ce este o conexiune business)](https://lanachat.ai/guides/ro/connect-telegram/)