# API: Telegram-Konten, Pools und Stories

_API · 8 Min. Lesezeit · Aktualisiert 2026-10-22 · https://lanachat.ai/guides/de/api-telegram-accounts/_

Ein **Telegram-Konto** ist ein Konto einer Creatorin, das über eine Geschäftsanbindung (ein Bot, den sie in ihren Telegram-Einstellungen hinzufügt) mit LanaChat verbunden ist. Konten werden in **Pools** gruppiert: Ein Pool besteht aus einer Creatorin, einem Markt und einer Traffic-Quelle, und neue Konversationen von einem Tracking-Link werden auf die sendenden Konten des passenden Pools verteilt. **Stories** werden gleichzeitig auf einem oder mehreren Konten gepostet.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/accounts` | Konten auflisten (`creator_id=`, `health=connected,pending,expired`) | `can_setup` | Planned |
| POST | `/accounts` | Ein Konto mit seinem Bot-Token hinzufügen; vor dem Speichern mit Telegram geprüft | `can_setup` | Planned |
| GET | `/accounts/{id}` | Ein Konto, dessen Status und Auslastung in dieser Stunde | `can_setup` | Planned |
| PATCH | `/accounts/{id}` | Gehirn, Markt, Traffic, Alias oder Antwortsprache ändern; ein- oder ausschalten | `can_setup` | Planned |
| DELETE | `/accounts/{id}` | Konto trennen (Konversationen bleiben erhalten) | `can_setup` | Planned |
| POST | `/accounts/{id}/check` | Verbindung jetzt testen statt auf die stündliche Prüfung zu warten | `can_setup` | Planned |
| GET | `/pools` | Alle Pools mit ihren Konten, Kapazität und Status | `can_tracking` | Planned |
| GET | `/pools/settings` | Stündliches Limit des Workspaces und Verteilungsregeln | `can_tracking` | Planned |
| PUT | `/pools/settings` | Stündliches Limit (100 bis 100.000) und Verteilung ändern | `can_tracking` | Planned |
| PATCH | `/pools/accounts/{account_id}` | Konto in den Pool aufnehmen oder entfernen, pausieren, Gewicht oder Stundenlimit setzen | `can_tracking` | Planned |
| GET | `/pools/events` | Pool-Protokoll: Flood-Wartezeiten, Pausen, Fortsetzungen, gehaltene Links | `can_tracking` | Planned |
| GET | `/stories` | Gepostete und geplante Stories (`creator_id=`, `status=`) | `can_setup` | Planned |
| POST | `/stories` | Eine Story jetzt posten oder auf einem oder mehreren Konten planen | `can_setup` | Planned |
| GET | `/stories/{id}` | Eine Story mit ihren Aufrufen, Reaktionen und Link-Klicks | `can_setup` | Planned |
| DELETE | `/stories/{id}` | Eine geplante Story abbrechen | `can_setup` | Planned |

## Das Konto-Objekt

```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 | Beginnt mit `acc_` |
| `creator_id` | string | Die Creatorin, zu der dieses Konto gehört |
| `username` | string | Der Telegram-@username des Kontos, ohne das @ |
| `bot_username` | string | Der Bot, der über die Geschäftsanbindung verknüpft ist |
| `health` | string | `connected`, `pending` oder `expired` |
| `active` | boolean | `false`, wenn das Konto ausgeschaltet ist: die KI antwortet nicht |
| `brain_id` | string oder null | Das AI Brain, das auf diesem Konto antwortet |
| `pool_id` | string | Der Pool, in den es durch `market` und `traffic` einsortiert wird |
| `market` | string | Sprachmarkt, z. B. `fr`, `en`, `pt-BR` oder `all` |
| `traffic` | string | Traffic-Quelle, z. B. `instagram` oder `tiktok` |
| `story_rights` | boolean | Ob die Geschäftsanbindung LanaChat erlaubt, Stories zu posten |
| `last_activity_at` | string | Letzte gesendete oder empfangene Nachricht, ISO 8601 UTC |

- `health` ist `connected`, `pending` (die Geschäftsanbindung ist noch nicht bestätigt) oder `expired` (der Bot hat keinen Zugriff mehr; erneut verbinden).
- Das Bot-Token wird nie zurückgegeben. LanaChat fragt niemals nach Telefonnummer, Passwort oder 2FA-Code.

## Konten

### Konten auflisten

`GET /accounts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Nein | Nur die Konten dieser Creatorin |
| `health` | string | Nein | `connected`, `pending` oder `expired`; mehrere durch Kommas getrennt |
| `limit`, `cursor` | number, string | Nein | [Pagination](https://lanachat.ai/guides/de/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
}
```

### Konto hinzufügen

`POST /accounts` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Ja | Die Creatorin, zu der das Konto gehört |
| `bot_token` | string | Ja | Das Token des Bots, den sie in ihren Telegram Business-Einstellungen verknüpft hat |
| `market` | string | Nein | Sprachmarkt, z. B. `fr` |
| `traffic` | string | Nein | Traffic-Quelle, z. B. `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
}
```

Die Antwort ist das Konto (`201`) mit `health: "pending"`, bis die Creatorin die Geschäftsanbindung in Telegram bestätigt. Das Bot-Token wird vor dem Speichern mit Telegram geprüft: Ein von Telegram abgelehntes Token antwortet mit `400`. Ein Konto, das bereits in einem anderen Workspace aktiv ist, wird abgelehnt (`409`). Jedes Konto benötigt eine Lizenz zum Antworten: siehe [Billing](https://lanachat.ai/guides/de/api-billing/).

### Konto abrufen

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

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

Die Antwort ist das Konto-Objekt mit seiner Auslastung in dieser Stunde. Eine unbekannte ID antwortet mit `404`.

### Konto aktualisieren

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `brain_id` | string | Nein | Das Brain, das auf diesem Konto antwortet |
| `market` | string | Nein | Sprachmarkt; verschiebt das Konto in den passenden Pool |
| `traffic` | string | Nein | Traffic-Quelle; verschiebt das Konto in den passenden Pool |
| `active` | boolean | Nein | `false` schaltet das Konto aus, `true` wieder ein |

Alias und Antwortsprache des Kontos können auf dieselbe Weise geändert werden.

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

Die Antwort ist das aktualisierte Konto. Das Ausschalten des letzten sendenden Kontos einer Creatorin mit aktiven Links antwortet mit `409`.

### Konto trennen

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

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

Die Konversationen bleiben erhalten. Das Entfernen des letzten sendenden Kontos einer Creatorin mit aktiven Links wird mit `409` abgelehnt.

### Verbindung jetzt prüfen

`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 prüft jedes Konto einmal pro Stunde; dieser Aufruf testet es sofort. Die Antwort ist das Konto mit seinem aktuellen `health`.

## Pools

Ein Pool entsteht durch die Tags seiner Konten (`market` und `traffic`); es gibt nichts zu erstellen. Eine neue Konversation geht an den Pool, dessen Traffic mit der Linkquelle übereinstimmt und dessen Markt zur Sprache des Fans passt, dann an den "All traffic"-Pool der Creatorin, dann an einen ihrer Pools, die noch senden. Bestehende Konversationen bleiben immer auf ihrem Konto.

### Pools auflisten

`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` ist `sending`, `near` (80 % der Kapazität), `saturated` (95 %) oder `none` (kein sendendes Konto).

### Pool-Einstellungen abrufen

`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 | Nachrichten, die der gesamte Workspace in einer rollierenden Stunde senden darf, 100 bis 100.000 |
| `default_limit_per_hour` | number | Stündliches Limit für ein neues Konto im Pool |
| `distribution.mode` | string | `weighted` (zufällig, proportional zum Gewicht jedes Kontos), `round_robin` (jedes Konto der Reihe nach) oder `least_loaded` (das Konto, das am weitesten vom Limit entfernt ist) |
| `distribution.warmup` | boolean | Ein neues Konto startet mit 50 Nachrichten pro Stunde und erreicht sein volles Limit am Tag 7 |
| `distribution.hold_when_saturated` | boolean | Wenn kein Konto einen neuen Fan aufnehmen kann, wird der Fan gehalten, bis eines frei wird, zuerst der älteste; sonst bekommt der Fan das am wenigsten ausgelastete Konto, auch über dem Limit |

Wenn der Workspace das `cap_per_hour` erreicht, leiten Links weiter, aber neue Konversationen werden gehalten, bis die Stunde unter das Limit fällt.

### Pool-Einstellungen ändern

`PUT /pools/settings` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `cap_per_hour` | number | Ja | 100 bis 100.000, ganze Zahl |
| `default_limit_per_hour` | number | Ja | 10 bis 1.000, ganze Zahl |
| `distribution` | object | Ja | `mode`, `warmup` und `hold_when_saturated`, wie oben |

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

Die Antwort sind die neuen Einstellungen. Ein Limit außerhalb von 100 bis 100.000 antwortet mit `400`.

### Konto im Pool ändern

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `in_pool` | boolean | Nein | `false` nimmt das Konto aus dem Pool: es behält seine Konversationen, bekommt aber keine neuen Fans |
| `paused` | boolean | Nein | `true` pausiert es im Pool |
| `weight` | number | Nein | 0 bis 100; Anteil neuer Fans im `weighted`-Modus (0 erlaubt: keine neuen Fans) |
| `limit_per_hour` | number | Nein | 10 bis 1.000 Nachrichten pro Stunde für dieses Konto |

```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` ist `active` oder `flood_wait`: Bei einem Telegram-Flood-Wartebefehl pausiert das Konto bis `flood_wait_until` und setzt dann selbstständig fort.
- Während der Aufwärmphase (`warmup_day` 1 bis 7) sendet das Konto weniger als sein `limit_per_hour`: 50 Nachrichten pro Stunde am Tag 1, das volle Limit am Tag 7.
- Das Herausnehmen, Pausieren oder Entfernen des letzten sendenden Kontos einer Creatorin mit aktiven Links wird mit `409` abgelehnt.

### Pool-Protokoll lesen

`GET /pools/events` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Nein | Nur die Events der Konten dieser Creatorin |
| `limit`, `cursor` | number, string | Nein | [Pagination](https://lanachat.ai/guides/de/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` ist `flood_wait`, `account_paused`, `resumed`, `link_paused` (das Workspace-Limit wurde erreicht, neue Fans werden gehalten), `account_added`, `account_removed` oder `settings`. `text` ist ein einfacher englischer Satz.

## Stories

### Stories auflisten

`GET /stories` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Nein | Nur die Stories dieser Creatorin |
| `status` | string | Nein | Zum Beispiel `scheduled` |
| `limit`, `cursor` | number, string | Nein | [Pagination](https://lanachat.ai/guides/de/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
}
```

### Story posten

`POST /stories` · `can_setup`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_ids` | array of strings | Ja | Die Konten, die sie posten |
| `media_id` | string | Ja | Ein Foto oder Video aus dem [Vault](https://lanachat.ai/guides/de/api-vault/) der Creatorin |
| `text` | string | Nein | Bildunterschrift |
| `link_id` | string | Nein | Ein [Tracking-Link](https://lanachat.ai/guides/de/api-tracking/), der in der Story angezeigt wird |
| `duration_hours` | number | Nein | Wie lange die Story sichtbar bleibt |
| `run_at` | string oder null | Nein | Wann sie gepostet wird (ISO 8601 UTC); weglassen für sofort |

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

Ein Konto ohne das Recht "manage stories" in seiner Geschäftsanbindung (`story_rights: false`) wird abgelehnt, mit dem Grund in `message`.

### Story abrufen

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

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

Die Antwort ist die Story mit ihren Aufrufen, Reaktionen und Link-Klicks, sobald sie gepostet wurde.

### Geplante Story abbrechen

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

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

Nur eine geplante Story kann abgebrochen werden.

## Verwandte Artikel

- [LanaChat API: Schnellstart, Authentifizierung und Fehler](https://lanachat.ai/guides/de/api-overview/)
- [Telegram-Konten: Konten, Pool-Auslastung und Stories](https://lanachat.ai/guides/de/telegram-accounts/)
- [Telegram-Konten verbinden (und was eine Business-Verbindung ist)](https://lanachat.ai/guides/de/connect-telegram/)