# API: Telegram-акаунти, пули та історії

_API · Читання 8 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/api-telegram-accounts/_

**Telegram-акаунт**, це один акаунт авторки, підключений до LanaChat через бізнес-зв’язок (бот, якого вона додає у своїх налаштуваннях Telegram). Акаунти згруповані у **пули**: пул, це одна авторка, один ринок і одне джерело трафіку, а нові розмови з трекінгового посилання розподіляються між акаунтами потрібного пулу. **Історії** публікуються одночасно на одному або кількох акаунтах.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/accounts` | Список акаунтів (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Додати акаунт з токеном бота; перевіряється у Telegram перед збереженням | `can_setup` | Planned |
| GET | `/accounts/{id}` | Один акаунт, його стан і навантаження за годину | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Змінити brain, ринок, трафік, псевдонім або мову відповіді; увімкнути або вимкнути | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Відключити акаунт (розмови збережені) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Перевірити з’єднання зараз замість очікування щогодинної перевірки | `can_setup` | Planned |
| GET | `/pools` | Кожен пул з акаунтами, місткістю та статусом | `can_tracking` | Planned |
| GET | `/pools/settings` | Щогодинний ліміт робочого простору та правила розподілу | `can_tracking` | Planned |
| PUT | `/pools/settings` | Змінити щогодинний ліміт (100-100000) і розподіл | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Взяти акаунт у пул або вивести з нього, призупинити, встановити вагу або ліміт за годину | `can_tracking` | Planned |
| GET | `/pools/events` | Лог пулу: очікування через flood wait, паузи, відновлення, утримання посилань | `can_tracking` | Planned |
| GET | `/stories` | Опубліковані та заплановані історії (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Опублікувати історію зараз або запланувати на одному чи кількох акаунтах | `can_setup` | Planned |
| GET | `/stories/{id}` | Одна історія з переглядами, реакціями та кліками по посиланнях | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Скасувати заплановану історію | `can_setup` | Planned |

## Об’єкт акаунта

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

| Поле | Тип | Опис |
|---|---|---|
| `id` | string | Починається з `acc_` |
| `creator_id` | string | Авторка, якій належить акаунт |
| `username` | string | Telegram @username акаунта без знаку @ |
| `bot_username` | string | Бот, пов’язаний через бізнес-зв’язок |
| `health` | string | `connected`, `pending` або `expired` |
| `active` | boolean | `false`, якщо акаунт вимкнено: AI не відповідає |
| `brain_id` | string або null | AI Brain, що відповідає на цьому акаунті |
| `pool_id` | string | Пул, до якого належить акаунт за тегами `market` і `traffic` |
| `market` | string | Ринок мови, наприклад `fr`, `en`, `pt-BR` або `all` |
| `traffic` | string | Джерело трафіку, наприклад `instagram` або `tiktok` |
| `story_rights` | boolean | Чи дозволяє бізнес-зв’язок LanaChat публікувати історії |
| `last_activity_at` | string | Час останнього надісланого або отриманого повідомлення, ISO 8601 UTC |

- `health` може бути `connected`, `pending` (бізнес-зв’язок ще не підтверджено) або `expired` (бот втратив доступ; потрібно перепідключити).
- Токен бота ніколи не повертається. LanaChat ніколи не запитує номер телефону, пароль або код 2FA.

## Акаунти

### Список акаунтів

`GET /accounts` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Ні | Тільки акаунти цієї авторки |
| `health` | string | Ні | `connected`, `pending` або `expired`; кілька через кому |
| `limit`, `cursor` | number, string | Ні | [Пагінація](https://lanachat.ai/guides/uk/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
}
```

### Додати акаунт

`POST /accounts` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Так | Авторка, якій належить акаунт |
| `bot_token` | string | Так | Токен бота, якого вона пов’язала у бізнес-налаштуваннях Telegram |
| `market` | string | Ні | Ринок мови, наприклад `fr` |
| `traffic` | string | Ні | Джерело трафіку, наприклад `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
}
```

Відповідь, акаунт (`201`) зі статусом `health: "pending"` до підтвердження бізнес-зв’язку авторкою в Telegram. Токен бота перевіряється у Telegram перед збереженням: токен, який Telegram відхиляє, повертає `400`. Акаунт, що вже активний в іншому робочому просторі, відхиляється (`409`). Кожен акаунт потребує ліцензії для відповіді: див. [Billing](https://lanachat.ai/guides/uk/api-billing/).

### Отримати акаунт

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

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

Відповідь, об’єкт акаунта з навантаженням за годину. Невідомий id повертає `404`.

### Оновити акаунт

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

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `brain_id` | string | Ні | Brain, що відповідає на цьому акаунті |
| `market` | string | Ні | Ринок мови; переміщує акаунт у відповідний пул |
| `traffic` | string | Ні | Джерело трафіку; переміщує акаунт у відповідний пул |
| `active` | boolean | Ні | `false` вимикає акаунт, `true` вмикає назад |

Псевдонім і мову відповіді акаунта можна змінити так само.

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

Відповідь, оновлений акаунт. Вимкнення останнього акаунта відправлення авторки, яка має активні посилання, повертає `409`.

### Відключити акаунт

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

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

Розмови збережені. Видалення останнього акаунта відправлення авторки з активними посиланнями повертає `409`.

### Перевірити з’єднання зараз

`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 перевіряє кожен акаунт раз на годину; цей виклик перевіряє негайно. Відповідь, акаунт з оновленим `health`.

## Пули

Пул формується тегами акаунтів (`market` і `traffic`); створювати його не потрібно. Нова розмова потрапляє у пул, де трафік відповідає джерелу посилання, а ринок, мові фана, потім у пул "All traffic" авторки, потім у будь-який її пул, що ще відправляє. Існуючі розмови завжди залишаються на своєму акаунті.

### Список пулів

`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` може бути `sending`, `near` (80% місткості), `saturated` (95%) або `none` (немає акаунтів, що відправляють).

### Отримати налаштування пулу

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

| Поле | Тип | Опис |
|---|---|---|
| `cap_per_hour` | number | Кількість повідомлень, які весь робочий простір може відправити за скользьку годину, від 100 до 100000 |
| `default_limit_per_hour` | number | Ліміт за годину для нового акаунта в пулі |
| `distribution.mode` | string | `weighted` (випадково пропорційно вазі акаунта), `round_robin` (по черзі), `least_loaded` (акаунт з найменшим навантаженням) |
| `distribution.warmup` | boolean | Новий акаунт починає з 50 повідомлень за годину, досягає повного ліміту на 7-й день |
| `distribution.hold_when_saturated` | boolean | Якщо жоден акаунт не може прийняти нового фана, утримувати фана до звільнення акаунта (спочатку найстаріший); інакше віддавати фана акаунту з найменшим навантаженням навіть понад ліміт |

Коли робочий простір досягає `cap_per_hour`, посилання продовжують перенаправляти, але нові розмови утримуються, доки ліміт не знизиться.

### Змінити налаштування пулу

`PUT /pools/settings` · `can_tracking`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `cap_per_hour` | number | Так | 100-100000, ціле число |
| `default_limit_per_hour` | number | Так | 10-1000, ціле число |
| `distribution` | object | Так | `mode`, `warmup` і `hold_when_saturated`, як вище |

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

Відповідь, нові налаштування. Ліміт поза 100-100000 повертає `400`.

### Змінити акаунт у пулі

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

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `in_pool` | boolean | Ні | `false` виводить акаунт з пулу: розмови збережені, але нові фани не надходять |
| `paused` | boolean | Ні | `true` призупиняє акаунт у пулі |
| `weight` | number | Ні | 0-100; частка нових фанів у режимі `weighted` (0 означає без нових фанів) |
| `limit_per_hour` | number | Ні | 10-1000 повідомлень за годину для цього акаунта |

```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` або `flood_wait`: при Telegram flood wait акаунт призупиняється до `flood_wait_until`, потім автоматично відновлюється.
- Під час розігріву (`warmup_day` від 1 до 7) акаунт відправляє менше за `limit_per_hour`: 50 повідомлень за годину в перший день, повний ліміт на 7-й.
- Виведення, пауза або видалення останнього акаунта відправлення авторки з активними посиланнями відхиляється (`409`).

### Прочитати лог пулу

`GET /pools/events` · `can_tracking`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Ні | Тільки події акаунтів цієї авторки |
| `limit`, `cursor` | number, string | Ні | [Пагінація](https://lanachat.ai/guides/uk/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`, `flood_wait`, `account_paused`, `resumed`, `link_paused` (досягнуто ліміт робочого простору, нові фани утримуються), `account_added`, `account_removed` або `settings`. `text`, просте речення англійською.

## Історії

### Список історій

`GET /stories` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `creator_id` | string | Ні | Тільки історії цієї авторки |
| `status` | string | Ні | Наприклад, `scheduled` |
| `limit`, `cursor` | number, string | Ні | [Пагінація](https://lanachat.ai/guides/uk/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
}
```

### Опублікувати історію

`POST /stories` · `can_setup`

| Параметр | Тип | Обов’язковий | Опис |
|---|---|---|---|
| `account_ids` | масив рядків | Так | Акаунти, що публікують історію |
| `media_id` | string | Так | Фото або відео з [Vault](https://lanachat.ai/guides/uk/api-vault/) авторки |
| `text` | string | Ні | Підпис |
| `link_id` | string | Ні | [Трекінгове посилання](https://lanachat.ai/guides/uk/api-tracking/), що показується в історії |
| `duration_hours` | number | Ні | Як довго історія буде доступна |
| `run_at` | string або null | Ні | Коли опублікувати (ISO 8601 UTC); пропустити, щоб опублікувати зараз |

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

Акаунт без права "manage stories" у бізнес-зв’язку (`story_rights: false`) отримує відмову з причиною у `message`.

### Отримати історію

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

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

Відповідь, історія з переглядами, реакціями та кліками по посиланнях після публікації.

### Скасувати заплановану історію

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

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

Можна скасувати лише заплановану історію.

## Пов’язані статті

- [LanaChat API: швидкий старт, автентифікація та помилки](https://lanachat.ai/guides/uk/api-overview/)
- [Облікові записи Telegram: облікові записи, завантаження пулу та історії](https://lanachat.ai/guides/uk/telegram-accounts/)
- [Підключення Telegram-акаунтів (і що таке бізнес-зв’язок)](https://lanachat.ai/guides/uk/connect-telegram/)