# API: Аккаунты Telegram, пулы и истории

_API · Чтение 8 мин · Обновлено 2026-10-22 · https://lanachat.ai/guides/ru/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, паузы, возобновления, удержания ссылок | `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/ru/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/ru/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/ru/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/ru/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/ru/api-vault/) автора |
| `text` | string | Нет | Подпись |
| `link_id` | string | Нет | [Трекинговая ссылка](https://lanachat.ai/guides/ru/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/ru/api-overview/)
- [Аккаунты Telegram: аккаунты, загрузка пула и истории](https://lanachat.ai/guides/ru/telegram-accounts/)
- [Подключение аккаунтов Telegram (и что такое бизнес-связь)](https://lanachat.ai/guides/ru/connect-telegram/)