# API: Cuentas de Telegram, pools e historias

_API · 8 min de lectura · Actualizado 2026-10-22 · https://lanachat.ai/guides/es/api-telegram-accounts/_

Una **cuenta de Telegram** es una cuenta de una creadora, conectada a LanaChat mediante una conexión comercial (un bot que ella añade en la configuración de Telegram). Las cuentas se agrupan en **pools**: un pool es una creadora, un mercado y una fuente de tráfico, y las nuevas conversaciones de un enlace de seguimiento se distribuyen entre las cuentas emisoras del pool correcto. Las **historias** se publican en una o más cuentas a la vez.

## Endpoints

| Método | Ruta | Descripción | Permiso | Estado |
|---|---|---|---|---|
| GET | `/accounts` | Listar cuentas (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Añadir una cuenta con su token de bot; verificado con Telegram antes de guardar | `can_setup` | Planned |
| GET | `/accounts/{id}` | Una cuenta, su estado y su carga esta hora | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Cambiar su brain, mercado, tráfico, alias o idioma de respuesta; activarla o desactivarla | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Desconectar la cuenta (se mantienen sus conversaciones) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Probar la conexión ahora en lugar de esperar la comprobación horaria | `can_setup` | Planned |
| GET | `/pools` | Todos los pools con sus cuentas, capacidad y estado | `can_tracking` | Planned |
| GET | `/pools/settings` | Límite horario del workspace y reglas de distribución | `can_tracking` | Planned |
| PUT | `/pools/settings` | Cambiar el límite horario (100 a 100,000) y la distribución | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Incluir o excluir una cuenta del pool, pausarla, ajustar su peso o límite horario | `can_tracking` | Planned |
| GET | `/pools/events` | Registro del pool: esperas por flood, pausas, reanudaciones, enlaces retenidos | `can_tracking` | Planned |
| GET | `/stories` | Historias publicadas y programadas (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Publicar una historia ahora o programarla en una o más cuentas | `can_setup` | Planned |
| GET | `/stories/{id}` | Una historia con sus vistas, reacciones y clics en enlaces | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Cancelar una historia programada | `can_setup` | Planned |

## El objeto cuenta

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

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | Empieza con `acc_` |
| `creator_id` | string | La creadora a la que pertenece esta cuenta |
| `username` | string | El @username de Telegram de la cuenta, sin el @ |
| `bot_username` | string | El bot vinculado mediante la conexión comercial |
| `health` | string | `connected`, `pending` o `expired` |
| `active` | boolean | `false` cuando la cuenta está apagada: la IA no responde en ella |
| `brain_id` | string o null | El AI Brain que responde en esta cuenta |
| `pool_id` | string | El pool al que pertenece según sus etiquetas `market` y `traffic` |
| `market` | string | Mercado de idioma, por ejemplo `fr`, `en`, `pt-BR` o `all` |
| `traffic` | string | Fuente de tráfico, por ejemplo `instagram` o `tiktok` |
| `story_rights` | boolean | Si la conexión comercial permite a LanaChat publicar historias |
| `last_activity_at` | string | Último mensaje enviado o recibido, ISO 8601 UTC |

- `health` puede ser `connected`, `pending` (la conexión comercial aún no está confirmada) o `expired` (el bot perdió acceso; reconéctalo).
- El token del bot nunca se devuelve. LanaChat nunca pide número de teléfono, contraseña ni código 2FA.

## Cuentas

### Listar cuentas

`GET /accounts` · `can_setup`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `creator_id` | string | No | Solo las cuentas de esta creadora |
| `health` | string | No | `connected`, `pending` o `expired`; varios separados por comas |
| `limit`, `cursor` | number, string | No | [Paginación](https://lanachat.ai/guides/es/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
}
```

### Añadir una cuenta

`POST /accounts` · `can_setup`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `creator_id` | string | Sí | La creadora a la que pertenece la cuenta |
| `bot_token` | string | Sí | El token del bot que vinculó en la configuración Business de Telegram |
| `market` | string | No | Mercado de idioma, por ejemplo `fr` |
| `traffic` | string | No | Fuente de tráfico, por ejemplo `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
}
```

La respuesta es la cuenta (`201`) con `health: "pending"` hasta que la creadora confirme la conexión comercial en Telegram. El token del bot se verifica con Telegram antes de guardar nada: un token rechazado por Telegram responde `400`. Una cuenta ya activa en otro workspace es rechazada (`409`). Cada cuenta necesita una licencia para responder: ver [Billing](https://lanachat.ai/guides/es/api-billing/).

### Obtener una cuenta

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

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

La respuesta es el objeto cuenta, con su carga esta hora. Un id desconocido responde `404`.

### Actualizar una cuenta

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

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `brain_id` | string | No | El brain que responde en esta cuenta |
| `market` | string | No | Mercado de idioma; mueve la cuenta al pool correspondiente |
| `traffic` | string | No | Fuente de tráfico; mueve la cuenta al pool correspondiente |
| `active` | boolean | No | `false` apaga la cuenta, `true` la enciende |

El alias y el idioma de respuesta de la cuenta pueden cambiarse igual.

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

La respuesta es la cuenta actualizada. Apagar la última cuenta emisora de una creadora con enlaces activos responde `409`.

### Desconectar una cuenta

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

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

Se mantienen sus conversaciones. Quitar la última cuenta emisora de una creadora con enlaces activos responde `409`.

### Comprobar la conexión ahora

`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 comprueba cada cuenta una vez por hora; esta llamada la prueba ahora. La respuesta es la cuenta con su estado `health` actualizado.

## Pools

Un pool se forma por las etiquetas de sus cuentas (`market` y `traffic`); no hay nada que crear. Una nueva conversación va al pool cuyo tráfico coincide con la fuente del enlace y cuyo mercado coincide con el idioma del fan, luego al pool "All traffic" de la creadora, luego a cualquiera de sus pools que aún envíen. Las conversaciones existentes siempre permanecen en su cuenta.

### 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` es `sending`, `near` (80% de su capacidad), `saturated` (95%) o `none` (sin cuenta emisora).

### Obtener la configuración del 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 }
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `cap_per_hour` | number | Mensajes que todo el workspace puede enviar en una hora móvil, 100 a 100,000 |
| `default_limit_per_hour` | number | Límite horario dado a una cuenta nueva en el pool |
| `distribution.mode` | string | `weighted` (aleatorio, proporcional al peso de cada cuenta), `round_robin` (cada cuenta por turno) o `least_loaded` (la cuenta más alejada de su límite) |
| `distribution.warmup` | boolean | Una cuenta nueva empieza con 50 mensajes/hora y alcanza su límite completo en 7 días |
| `distribution.hold_when_saturated` | boolean | Cuando ninguna cuenta puede tomar un fan nuevo, retener al fan hasta que una se libere, el más antiguo primero; si no, dar el fan a la cuenta menos cargada aunque supere su límite |

Cuando el workspace alcanza `cap_per_hour`, los enlaces siguen redirigiendo pero las nuevas conversaciones se retienen hasta que la hora baje del límite.

### Cambiar la configuración del pool

`PUT /pools/settings` · `can_tracking`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `cap_per_hour` | number | Sí | 100 a 100,000, número entero |
| `default_limit_per_hour` | number | Sí | 10 a 1,000, número entero |
| `distribution` | object | Sí | `mode`, `warmup` y `hold_when_saturated`, como arriba |

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

La respuesta es la nueva configuración. Un límite fuera de 100 a 100,000 responde `400`.

### Cambiar una cuenta en el pool

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

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `in_pool` | boolean | No | `false` saca la cuenta del pool: mantiene sus conversaciones pero no recibe fans nuevos |
| `paused` | boolean | No | `true` la pausa en el pool |
| `weight` | number | No | 0 a 100; proporción de fans nuevos en modo `weighted` (0 permitido: sin fans nuevos) |
| `limit_per_hour` | number | No | 10 a 1,000 mensajes por hora para esta cuenta |

```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` es `active` o `flood_wait`: en un flood wait de Telegram la cuenta se pausa hasta `flood_wait_until`, luego se reanuda sola.
- Durante el calentamiento (`warmup_day` 1 a 7) la cuenta envía menos que su `limit_per_hour`: 50 por hora el día 1, el límite completo el día 7.
- Sacar, pausar o eliminar la última cuenta emisora de una creadora con enlaces activos es rechazado (`409`).

### Leer el registro del pool

`GET /pools/events` · `can_tracking`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `creator_id` | string | No | Solo eventos de las cuentas de esta creadora |
| `limit`, `cursor` | number, string | No | [Paginación](https://lanachat.ai/guides/es/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` es `flood_wait`, `account_paused`, `resumed`, `link_paused` (se alcanzó el límite del workspace, se retienen fans nuevos), `account_added`, `account_removed` o `settings`. `text` es una frase en inglés simple.

## Historias

### Listar historias

`GET /stories` · `can_setup`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `creator_id` | string | No | Solo las historias de esta creadora |
| `status` | string | No | Por ejemplo `scheduled` |
| `limit`, `cursor` | number, string | No | [Paginación](https://lanachat.ai/guides/es/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
}
```

### Publicar una historia

`POST /stories` · `can_setup`

| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| `account_ids` | array de strings | Sí | Las cuentas que la publican |
| `media_id` | string | Sí | Una foto o video del [Vault](https://lanachat.ai/guides/es/api-vault/) de la creadora |
| `text` | string | No | Pie de foto |
| `link_id` | string | No | Un [tracking link](https://lanachat.ai/guides/es/api-tracking/) mostrado en la historia |
| `duration_hours` | number | No | Cuánto tiempo permanece la historia |
| `run_at` | string o null | No | Cuándo publicarla (ISO 8601 UTC); omitir para publicar ahora |

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

Una cuenta sin el derecho "manage stories" en su conexión comercial (`story_rights: false`) es rechazada, con la razón en `message`.

### Obtener una historia

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

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

La respuesta es la historia con sus vistas, reacciones y clics en enlaces una vez publicada.

### Cancelar una historia programada

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

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

Solo se puede cancelar una historia programada.

## Artículos relacionados

- [API de LanaChat: inicio rápido, autenticación y errores](https://lanachat.ai/guides/es/api-overview/)
- [Cuentas de Telegram: cuentas, carga del pool e historias](https://lanachat.ai/guides/es/telegram-accounts/)
- [Conectar cuentas de Telegram (y qué es una conexión comercial)](https://lanachat.ai/guides/es/connect-telegram/)