# API: Konta Telegram, pule i historie

_API · 8 min czytania · Zaktualizowano 2026-10-22 · https://lanachat.ai/guides/pl/api-telegram-accounts/_

Konto **Telegram** to jedno konto twórczyni, połączone z LanaChat przez połączenie biznesowe (bota, którego dodaje w ustawieniach Telegram). Konta są pogrupowane w **pule**: pula to jedna twórczyni, jeden rynek i jedno źródło ruchu, a nowe rozmowy z linku śledzącego są rozdzielane pomiędzy konta wysyłające w odpowiedniej puli. **Historie** są publikowane na jednym lub kilku kontach jednocześnie.

## Endpointy

| Metoda | Ścieżka | Opis | Uprawnienie | Status |
|---|---|---|---|---|
| GET | `/accounts` | Lista kont (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Dodaj konto z tokenem bota; sprawdzane w Telegram przed zapisaniem | `can_setup` | Planned |
| GET | `/accounts/{id}` | Jedno konto, jego status i obciążenie w tej godzinie | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Zmień brain, rynek, ruch, alias lub język odpowiedzi; włącz lub wyłącz konto | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Odłącz konto (rozmowy pozostają) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Przetestuj połączenie teraz, zamiast czekać na godzinne sprawdzenie | `can_setup` | Planned |
| GET | `/pools` | Wszystkie pule z ich kontami, pojemnością i statusem | `can_tracking` | Planned |
| GET | `/pools/settings` | Godzinny limit workspace i zasady dystrybucji | `can_tracking` | Planned |
| PUT | `/pools/settings` | Zmień godzinny limit (100 do 100000) i dystrybucję | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Dodaj lub usuń konto z puli, wstrzymaj je, ustaw wagę lub limit godzinny | `can_tracking` | Planned |
| GET | `/pools/events` | Log puli: oczekiwania na flood, pauzy, wznowienia, wstrzymane linki | `can_tracking` | Planned |
| GET | `/stories` | Opublikowane i zaplanowane historie (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Opublikuj historię teraz lub zaplanuj na jednym lub kilku kontach | `can_setup` | Planned |
| GET | `/stories/{id}` | Jedna historia z wyświetleniami, reakcjami i kliknięciami linków | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Anuluj zaplanowaną historię | `can_setup` | Planned |

## Obiekt konta

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

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Zaczyna się od `acc_` |
| `creator_id` | string | Twórczyni, do której należy konto |
| `username` | string | Telegram @username konta, bez @ |
| `bot_username` | string | Bot powiązany przez połączenie biznesowe |
| `health` | string | `connected`, `pending` lub `expired` |
| `active` | boolean | `false` gdy konto jest wyłączone: AI na nim nie odpowiada |
| `brain_id` | string lub null | AI Brain odpowiadający na tym koncie |
| `pool_id` | string | Pula, do której konto należy według tagów `market` i `traffic` |
| `market` | string | Rynek językowy, np. `fr`, `en`, `pt-BR` lub `all` |
| `traffic` | string | Źródło ruchu, np. `instagram` lub `tiktok` |
| `story_rights` | boolean | Czy połączenie biznesowe pozwala LanaChat publikować historie |
| `last_activity_at` | string | Ostatnia wysłana lub odebrana wiadomość, ISO 8601 UTC |

- `health` to `connected`, `pending` (połączenie biznesowe niepotwierdzone) lub `expired` (bot stracił dostęp; połącz ponownie).
- Token bota nigdy nie jest zwracany. LanaChat nigdy nie prosi o numer telefonu, hasło ani kod 2FA.

## Konta

### Lista kont

`GET /accounts` · `can_setup`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `creator_id` | string | Nie | Tylko konta tej twórczyni |
| `health` | string | Nie | `connected`, `pending` lub `expired`; kilka oddzielonych przecinkami |
| `limit`, `cursor` | number, string | Nie | [Paginacja](https://lanachat.ai/guides/pl/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
}
```

### Dodaj konto

`POST /accounts` · `can_setup`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `creator_id` | string | Tak | Twórczyni, do której należy konto |
| `bot_token` | string | Tak | Token bota powiązanego w ustawieniach biznesowych Telegram |
| `market` | string | Nie | Rynek językowy, np. `fr` |
| `traffic` | string | Nie | Źródło ruchu, np. `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
}
```

Odpowiedź to konto (`201`) z `health: "pending"` aż twórczyni potwierdzi połączenie biznesowe w Telegram. Token bota jest sprawdzany w Telegram przed zapisem: token odrzucony przez Telegram zwraca `400`. Konto już aktywne w innym workspace jest odrzucane (`409`). Każde konto potrzebuje licencji do odpowiadania: patrz [Billing](https://lanachat.ai/guides/pl/api-billing/).

### Pobierz konto

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

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

Odpowiedź to obiekt konta z obciążeniem w tej godzinie. Nieznane id zwraca `404`.

### Aktualizuj konto

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

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `brain_id` | string | Nie | Brain odpowiadający na tym koncie |
| `market` | string | Nie | Rynek językowy; przenosi konto do odpowiadającej puli |
| `traffic` | string | Nie | Źródło ruchu; przenosi konto do odpowiadającej puli |
| `active` | boolean | Nie | `false` wyłącza konto, `true` włącza je z powrotem |

Alias i język odpowiedzi konta można zmienić w ten sam sposób.

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

Odpowiedź to zaktualizowane konto. Wyłączenie ostatniego konta wysyłającego twórczyni z aktywnymi linkami zwraca `409`.

### Odłącz konto

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

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

Rozmowy pozostają. Usunięcie ostatniego konta wysyłającego twórczyni z aktywnymi linkami zwraca `409`.

### Sprawdź połączenie teraz

`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 sprawdza każde konto co godzinę; to wywołanie testuje je teraz. Odpowiedź to konto z aktualnym `health`.

## Pule

Pula tworzona jest przez tagi kont (`market` i `traffic`); nic nie trzeba tworzyć ręcznie. Nowa rozmowa trafia do puli, której ruch odpowiada źródłu linku, a rynek językowy odpowiada językowi fana, potem do puli "All traffic" twórczyni, potem do dowolnej jej puli, która jeszcze wysyła. Istniejące rozmowy zawsze pozostają na swoim koncie.

### Lista pul

`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` to `sending`, `near` (80% pojemności), `saturated` (95%) lub `none` (brak konta wysyłającego).

### Pobierz ustawienia puli

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

| Pole | Typ | Opis |
|---|---|---|
| `cap_per_hour` | number | Liczba wiadomości, które workspace może wysłać w ruchomym oknie godzinnym, 100 do 100000 |
| `default_limit_per_hour` | number | Limit godzinny nadawany nowemu kontu w puli |
| `distribution.mode` | string | `weighted` (losowo, proporcjonalnie do wagi konta), `round_robin` (kolejno każde konto) lub `least_loaded` (konto najdalej od limitu) |
| `distribution.warmup` | boolean | Nowe konto zaczyna od 50 wiadomości na godzinę i osiąga pełny limit po 7 dniach |
| `distribution.hold_when_saturated` | boolean | Gdy żadne konto nie może przyjąć nowego fana, wstrzymaj fana do zwolnienia konta (najstarszy pierwszy); inaczej daj fana najmniej obciążonemu kontu nawet ponad limit |

Gdy workspace osiąga `cap_per_hour`, linki dalej przekierowują, ale nowe rozmowy są wstrzymywane aż limit spadnie.

### Zmień ustawienia puli

`PUT /pools/settings` · `can_tracking`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `cap_per_hour` | number | Tak | 100 do 100000, liczba całkowita |
| `default_limit_per_hour` | number | Tak | 10 do 1000, liczba całkowita |
| `distribution` | object | Tak | `mode`, `warmup` i `hold_when_saturated`, jak wyżej |

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

Odpowiedź to nowe ustawienia. Limit poza 100 do 100000 zwraca `400`.

### Zmień konto w puli

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

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `in_pool` | boolean | Nie | `false` usuwa konto z puli: rozmowy pozostają, ale nie dostaje nowych fanów |
| `paused` | boolean | Nie | `true` wstrzymuje konto w puli |
| `weight` | number | Nie | 0 do 100; udział nowych fanów w trybie `weighted` (0 oznacza brak nowych fanów) |
| `limit_per_hour` | number | Nie | 10 do 1000 wiadomości na godzinę dla tego konta |

```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` to `active` lub `flood_wait`: przy oczekiwaniu na flood Telegram konto samo się wstrzymuje do `flood_wait_until`, potem wznawia.
- Podczas rozruchu (`warmup_day` 1 do 7) konto wysyła mniej niż `limit_per_hour`: 50 na godzinę w dniu 1, pełny limit w dniu 7.
- Usunięcie, wstrzymanie lub wyjęcie ostatniego konta wysyłającego twórczyni z aktywnymi linkami jest odrzucane (`409`).

### Odczytaj log puli

`GET /pools/events` · `can_tracking`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `creator_id` | string | Nie | Tylko zdarzenia kont tej twórczyni |
| `limit`, `cursor` | number, string | Nie | [Paginacja](https://lanachat.ai/guides/pl/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` to `flood_wait`, `account_paused`, `resumed`, `link_paused` (osiągnięto limit workspace, nowi fani są wstrzymani), `account_added`, `account_removed` lub `settings`. `text` to zdanie po angielsku.

## Historie

### Lista historii

`GET /stories` · `can_setup`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `creator_id` | string | Nie | Tylko historie tej twórczyni |
| `status` | string | Nie | Na przykład `scheduled` |
| `limit`, `cursor` | number, string | Nie | [Paginacja](https://lanachat.ai/guides/pl/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
}
```

### Opublikuj historię

`POST /stories` · `can_setup`

| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
| `account_ids` | tablica stringów | Tak | Konta, które ją publikują |
| `media_id` | string | Tak | Zdjęcie lub wideo z [Vault](https://lanachat.ai/guides/pl/api-vault/) twórczyni |
| `text` | string | Nie | Podpis |
| `link_id` | string | Nie | [Link śledzący](https://lanachat.ai/guides/pl/api-tracking/) wyświetlany w historii |
| `duration_hours` | number | Nie | Jak długo historia jest widoczna |
| `run_at` | string lub null | Nie | Kiedy opublikować (ISO 8601 UTC); pomiń, by opublikować teraz |

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

Konto bez prawa "manage stories" w połączeniu biznesowym (`story_rights: false`) jest odrzucane, z powodem w `message`.

### Pobierz historię

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

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

Odpowiedź to historia z wyświetleniami, reakcjami i kliknięciami linków po opublikowaniu.

### Anuluj zaplanowaną historię

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

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

Anulować można tylko zaplanowaną historię.

## Powiązane artykuły

- [LanaChat API: szybki start, uwierzytelnianie i błędy](https://lanachat.ai/guides/pl/api-overview/)
- [Konta Telegram: konta, obciążenie puli i stories](https://lanachat.ai/guides/pl/telegram-accounts/)
- [Podłącz konta Telegram (i co to jest połączenie biznesowe)](https://lanachat.ai/guides/pl/connect-telegram/)