# API: Contas do Telegram, pools e stories

_API · Leitura de 8 min · Atualizado 2026-10-22 · https://lanachat.ai/guides/pt/api-telegram-accounts/_

Uma **conta do Telegram** é uma conta de uma criadora, conectada ao LanaChat por meio de uma conexão comercial (um bot que ela adiciona nas configurações do Telegram). As contas são agrupadas em **pools**: um pool é uma criadora, um mercado e uma fonte de tráfego, e novas conversas de um link de rastreamento são distribuídas entre as contas de envio do pool correto. **Stories** são postados em uma ou mais contas ao mesmo tempo.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/accounts` | Lista contas (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Adiciona uma conta com seu token de bot; verificado com o Telegram antes de salvar | `can_setup` | Planned |
| GET | `/accounts/{id}` | Uma conta, seu status e sua carga nesta hora | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Altera seu brain, mercado, tráfego, alias ou idioma de resposta; liga ou desliga | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Desconecta a conta (suas conversas são mantidas) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Testa a conexão agora em vez de esperar pela verificação horária | `can_setup` | Planned |
| GET | `/pools` | Todos os pools com suas contas, capacidade e status | `can_tracking` | Planned |
| GET | `/pools/settings` | Limite horário do workspace e regras de distribuição | `can_tracking` | Planned |
| PUT | `/pools/settings` | Altera o limite horário (100 a 100.000) e a distribuição | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Coloca ou tira uma conta do pool, pausa, define peso ou limite horário | `can_tracking` | Planned |
| GET | `/pools/events` | Log do pool: esperas por flood, pausas, retomadas, links retidos | `can_tracking` | Planned |
| GET | `/stories` | Stories postados e agendados (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Posta um story agora ou agenda em uma ou mais contas | `can_setup` | Planned |
| GET | `/stories/{id}` | Um story com suas visualizações, reações e cliques no link | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Cancela um story agendado | `can_setup` | Planned |

## O objeto conta

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

| Field | Type | Description |
|---|---|---|
| `id` | string | Começa com `acc_` |
| `creator_id` | string | A criadora a quem esta conta pertence |
| `username` | string | O @username do Telegram da conta, sem o @ |
| `bot_username` | string | O bot vinculado pela conexão comercial |
| `health` | string | `connected`, `pending` ou `expired` |
| `active` | boolean | `false` quando a conta está desligada: a IA não responde nela |
| `brain_id` | string ou null | O AI Brain que responde nesta conta |
| `pool_id` | string | O pool em que suas tags `market` e `traffic` a colocam |
| `market` | string | Mercado de idioma, por exemplo `fr`, `en`, `pt-BR` ou `all` |
| `traffic` | string | Fonte de tráfego, por exemplo `instagram` ou `tiktok` |
| `story_rights` | boolean | Se a conexão comercial permite que LanaChat poste stories |
| `last_activity_at` | string | Última mensagem enviada ou recebida, ISO 8601 UTC |

- `health` é `connected`, `pending` (a conexão comercial ainda não confirmada) ou `expired` (o bot perdeu acesso; reconecte).
- O token do bot nunca é retornado. LanaChat nunca pede número de telefone, senha ou código 2FA.

## Contas

### Listar contas

`GET /accounts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Não | Apenas as contas desta criadora |
| `health` | string | Não | `connected`, `pending` ou `expired`; vários separados por vírgulas |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/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
}
```

### Adicionar uma conta

`POST /accounts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Sim | A criadora a quem a conta pertence |
| `bot_token` | string | Sim | O token do bot que ela vinculou nas configurações comerciais do Telegram |
| `market` | string | Não | Mercado de idioma, por exemplo `fr` |
| `traffic` | string | Não | Fonte de tráfego, por exemplo `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
}
```

A resposta é a conta (`201`) com `health: "pending"` até a criadora confirmar a conexão comercial no Telegram. O token do bot é verificado com o Telegram antes de salvar: um token recusado pelo Telegram responde `400`. Uma conta já ativa em outro workspace é recusada (`409`). Cada conta precisa de uma licença para responder: veja [Billing](https://lanachat.ai/guides/pt/api-billing/).

### Obter uma conta

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

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

A resposta é o objeto conta, com sua carga nesta hora. Um id desconhecido responde `404`.

### Atualizar uma conta

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `brain_id` | string | Não | O brain que responde nesta conta |
| `market` | string | Não | Mercado de idioma; move a conta para o pool correspondente |
| `traffic` | string | Não | Fonte de tráfego; move a conta para o pool correspondente |
| `active` | boolean | Não | `false` desliga a conta, `true` liga novamente |

O alias e o idioma de resposta da conta podem ser alterados da mesma forma.

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

A resposta é a conta atualizada. Desligar a última conta de envio de uma criadora que tem links ativos responde `409`.

### Desconectar uma conta

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

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

Suas conversas são mantidas. Remover a última conta de envio de uma criadora com links ativos responde `409`.

### Testar a conexão agora

`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 verifica cada conta uma vez por hora; esta chamada testa agora. A resposta é a conta com seu `health` atualizado.

## Pools

Um pool é formado pelas tags das suas contas (`market` e `traffic`); não há nada a criar. Uma nova conversa vai para o pool cujo tráfego corresponde à fonte do link e cujo mercado corresponde ao idioma do fã, depois para o pool "All traffic" da criadora, depois para qualquer um de seus pools que ainda envia. Conversas existentes sempre permanecem em sua conta.

### Listar pools

`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% da capacidade), `saturated` (95%) ou `none` (sem conta enviando).

### Obter configurações do pool

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

| Field | Type | Description |
|---|---|---|
| `cap_per_hour` | number | Mensagens que todo o workspace pode enviar em uma hora móvel, 100 a 100.000 |
| `default_limit_per_hour` | number | Limite horário dado a uma nova conta no pool |
| `distribution.mode` | string | `weighted` (aleatório, proporcional ao peso de cada conta), `round_robin` (cada conta por vez) ou `least_loaded` (a conta mais distante do limite) |
| `distribution.warmup` | boolean | Uma conta nova começa com 50 mensagens por hora e alcança o limite total no dia 7 |
| `distribution.hold_when_saturated` | boolean | Quando nenhuma conta pode receber um novo fã, segura o fã até liberar, pelo mais antigo; senão dá para a conta menos carregada mesmo acima do limite |

Quando o workspace atinge `cap_per_hour`, os links continuam redirecionando, mas novas conversas são retidas até a hora cair abaixo do limite.

### Alterar configurações do pool

`PUT /pools/settings` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `cap_per_hour` | number | Sim | 100 a 100.000, número inteiro |
| `default_limit_per_hour` | number | Sim | 10 a 1.000, número inteiro |
| `distribution` | object | Sim | `mode`, `warmup` e `hold_when_saturated`, como acima |

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

A resposta são as novas configurações. Um limite fora de 100 a 100.000 responde `400`.

### Alterar uma conta no pool

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `in_pool` | boolean | Não | `false` tira a conta do pool: mantém suas conversas mas não recebe novos fãs |
| `paused` | boolean | Não | `true` pausa a conta no pool |
| `weight` | number | Não | 0 a 100; participação de novos fãs no modo `weighted` (0 é permitido: nenhum fã novo) |
| `limit_per_hour` | number | Não | 10 a 1.000 mensagens por hora para esta conta |

```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` ou `flood_wait`: em espera por flood do Telegram, a conta se pausa até `flood_wait_until`, depois retoma sozinha.
- Durante o aquecimento (`warmup_day` 1 a 7) a conta envia menos que seu `limit_per_hour`: 50 por hora no dia 1, limite total no dia 7.
- Tirar, pausar ou remover a última conta de envio de uma criadora com links ativos é recusado (`409`).

### Ler o log do pool

`GET /pools/events` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Não | Apenas eventos das contas desta criadora |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/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` (limite do workspace atingido, novos fãs retidos), `account_added`, `account_removed` ou `settings`. `text` é uma frase simples em inglês.

## Stories

### Listar stories

`GET /stories` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Não | Apenas stories desta criadora |
| `status` | string | Não | Por exemplo `scheduled` |
| `limit`, `cursor` | number, string | Não | [Paginação](https://lanachat.ai/guides/pt/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
}
```

### Postar um story

`POST /stories` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_ids` | array de strings | Sim | As contas que postam |
| `media_id` | string | Sim | Uma foto ou vídeo do [Vault](https://lanachat.ai/guides/pt/api-vault/) da criadora |
| `text` | string | Não | Legenda |
| `link_id` | string | Não | Um [tracking link](https://lanachat.ai/guides/pt/api-tracking/) mostrado no story |
| `duration_hours` | number | Não | Quanto tempo o story fica ativo |
| `run_at` | string ou null | Não | Quando postar (ISO 8601 UTC); omita para postar agora |

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

Uma conta sem o direito "manage stories" na conexão comercial (`story_rights: false`) é recusada, com o motivo em `message`.

### Obter um story

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

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

A resposta é o story com suas visualizações, reações e cliques no link após ser postado.

### Cancelar um story agendado

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

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

Só um story agendado pode ser cancelado.

## Artigos relacionados

- [API LanaChat: início rápido, autenticação e erros](https://lanachat.ai/guides/pt/api-overview/)
- [Contas do Telegram: contas, carga da pool e stories](https://lanachat.ai/guides/pt/telegram-accounts/)
- [Conecte contas do Telegram (e o que é uma conexão comercial)](https://lanachat.ai/guides/pt/connect-telegram/)