# API: Fans, Konversationen und Nachrichten

_API · 7 Min. Lesezeit · Aktualisiert 2026-10-22 · https://lanachat.ai/guides/de/api-conversations/_

Ein **fan** ist ein Telegram-Nutzer, der einer Ihrer Creatorinnen geschrieben hat. Eine **conversation** ist der Chat zwischen diesem Fan und einem Telegram-Account. Nachrichten werden von der KI, einem Teammitglied oder einem Skript gesendet. Diese Endpunkte entsprechen **Live Convs** und **Fans** in der Console.

## Endpunkte

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/fans` | Fans auflisten (`creator_id=`, `status=`, `list_id=`, `q=`, `spent_min=`) | `can_fan_read` | Planned |
| GET | `/fans/{id}` | Ein Fan: Sprachen, Ausgaben, Status, Listen, Notizen | `can_fan_read` | Planned |
| PATCH | `/fans/{id}` | Alias, Antwortsprache oder Notizen des Fans ändern | `can_chat` | Planned |
| GET | `/fans/{id}/sales` | Käufe des Fans | `can_sales_read` | Planned |
| POST | `/fans/import` | Frühere Fans und Nachrichten importieren (sendet nie etwas) | `can_fan_import` | Planned |
| GET | `/fan-lists` | Listen (VIPs, Win back…) | `can_fan_read` | Planned |
| POST | `/fan-lists` | Liste erstellen | `can_chat` | Planned |
| POST | `/fan-lists/{id}/members` | Fans zu einer Liste hinzufügen | `can_chat` | Planned |
| DELETE | `/fan-lists/{id}/members` | Fans aus einer Liste entfernen | `can_chat` | Planned |
| GET | `/conversations` | Konversationen auflisten (`creator_id=`, `account_id=`, `state=`, `unread=true`) | `can_fan_read` | Planned |
| GET | `/conversations/{id}` | Eine Konversation und wer antwortet | `can_fan_read` | Planned |
| GET | `/conversations/{id}/messages` | Nachrichten, neueste zuerst (`translate=en` fügt Übersetzung hinzu) | `can_fan_read` | Planned |
| POST | `/conversations/{id}/messages` | Nachricht als Creatorin senden (Text, Medien, Angebot) | `can_chat` | Planned |
| POST | `/conversations/{id}/reactions` | Reaktion auf eine Fan-Nachricht hinzufügen oder entfernen | `can_chat` | Planned |
| POST | `/conversations/{id}/takeover` | Eine Person übernimmt: Die KI antwortet diesem Fan nicht mehr | `can_chat` | Planned |
| POST | `/conversations/{id}/release` | Die Konversation an die KI zurückgeben | `can_chat` | Planned |
| POST | `/conversations/{id}/script` | Skript auf diese Konversation ausführen | `can_chat` | Planned |
| POST | `/conversations/{id}/read` | Konversation als gelesen markieren | `can_chat` | Planned |

## Das Fan-Objekt

```json
{
  "id": "fan_921",
  "display_name": "Marco",
  "username": "marco_dl",
  "creator_id": "cr_lea",
  "purchases": 9,
  "spent": { "stars": 1450, "net_cents": 1885 },
  "lists": ["vip"]
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Beginnt mit `fan_` |
| `display_name` | string | Name des Fans auf Telegram |
| `username` | string or null | Telegram-@username des Fans, ohne das @ |
| `creator_id` | string | Die Creatorin, an die dieser Fan geschrieben hat |
| `purchases` | number | Bisher bestätigte Käufe |
| `spent` | object | Gesamt ausgegeben: `stars` und `net_cents` in US-Cent nach Telegram-Anteil und Rückerstattungen |
| `lists` | array of strings | IDs der Fan-Listen, in denen dieser Fan ist |

Ein Fan enthält außerdem die verwendeten Sprachen, das Status-Tag, Teamnotizen, einen Alias und eine Antwortsprache wie auf der **Fans**-Seite.

## Das Konversationsobjekt

```json
{
  "id": "conv_1001_88231",
  "fan_id": "fan_921",
  "creator_id": "cr_lea",
  "account_id": "acc_1001",
  "state": "ai",
  "status": { "tag": "active", "reason": null },
  "unread": 2,
  "last_message_at": "2026-10-06T14:02:51Z",
  "spent": { "stars": 1450, "net_cents": 1885 },
  "source_link_id": "lnk_3"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Beginnt mit `conv_` |
| `fan_id`, `creator_id`, `account_id` | string | Wer mit wem spricht, auf welchem Telegram-Account |
| `state` | string | Wer antwortet: `ai`, `human` (übernommen), `script` (Skript läuft) oder `off` |
| `status` | object | `tag` (Status-Tags der Fans-Seite) und der `reason`, falls vorhanden |
| `unread` | number | Noch nicht gelesene Fan-Nachrichten |
| `last_message_at` | string | ISO 8601, UTC |
| `spent` | object | Was der Fan in dieser Konversation ausgegeben hat: `stars` und `net_cents` |
| `source_link_id` | string or null | Der Tracking-Link, über den der Fan kam |

`status.tag` entspricht den Status-Tags der Fans-Seite (`review`, `safety_hold`, `converted`, `lost`, `underage`…). Eine `off`-Konversation aus Sicherheitsgründen kann nicht an die KI zurückgegeben werden (`409`).

## Das Nachrichtenobjekt

```json
{
  "id": "msg_77120",
  "from": "creator",
  "sent_by": "ai",
  "text": "Made this one this morning…",
  "media": [ { "id": "med_5521", "locked": true, "stars": 300 } ],
  "at": "2026-10-06T14:02:51Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Beginnt mit `msg_` |
| `from` | string | `creator` oder `fan` |
| `sent_by` | string | Bei Creator-Nachrichten: `ai`, `human` oder `script` |
| `member_id` | string | Das Teammitglied, das gesendet hat, wenn `sent_by` `human` aus der Console ist |
| `token_id` | string | Das Zugriffstoken, das gesendet hat, wenn es von der API kam |
| `text` | string | Text der Nachricht |
| `media` | array | Gesendete Medien: `id`, `locked` (bezahlt und noch nicht gekauft) und Preis in `stars` |
| `reactions` | array | Reaktionen auf eine Fan-Nachricht |
| `status` | string | Für gesendete Nachrichten: `queued`, `sent`, `read` oder `failed` |
| `at` | string | ISO 8601, UTC |

`sent_by` bestimmt die Provisionsrate eines Verkaufs, wird also vom Server gesetzt und nie von Ihrer Anfrage.

## Das Verkaufsobjekt

```json
{
  "sale_id": "sale_8812",
  "fan_id": "fan_921",
  "creator_id": "cr_lea",
  "account_id": "acc_1001",
  "conversation_id": "conv_1001_88231",
  "stars": 300,
  "net_cents": 390,
  "sent_by": "ai",
  "kind": "offer"
}
```

| Field | Type | Description |
|---|---|---|
| `sale_id` | string | Beginnt mit `sale_` |
| `fan_id`, `creator_id`, `account_id`, `conversation_id` | string | Wer gekauft hat, von wem, wo |
| `stars` | number | Bezahlt in Telegram Stars |
| `net_cents` | number | Nettowert in US-Cent (ein Star zählt $0.013) |
| `sent_by` | string | `ai`, `human` oder `script`: Wer das Angebot gesendet hat, bestimmt die Provision |
| `kind` | string | Was gekauft wurde, z.B. `offer` |

Das gleiche Objekt kommt per [webhook](https://lanachat.ai/guides/de/api-webhooks/), Event `sale.completed`.

## Fans

### Fans auflisten

`GET /fans` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Nur die Fans dieser Creatorin |
| `status` | string | No | Ein Status-Tag der Fans-Seite, z.B. `converted` |
| `list_id` | string | No | Nur die Fans dieser Liste |
| `q` | string | No | Teil des Namens oder Usernamens des Fans |
| `spent_min` | number | No | Nur Fans, die mindestens so viele Stars ausgegeben haben |
| `limit`, `cursor` | number, string | No | [Paginierung](https://lanachat.ai/guides/de/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/fans?creator_id=cr_lea&spent_min=1000&limit=50" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "fan_921", "display_name": "Marco", "username": "marco_dl", "creator_id": "cr_lea", "purchases": 9, "spent": { "stars": 1450, "net_cents": 1885 }, "lists": ["vip"] }
  ],
  "next_cursor": null
}
```

### Einen Fan abrufen

`GET /fans/{id}` · `can_fan_read`

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

Die Antwort ist das Fan-Objekt. Eine unbekannte ID ergibt `404`.

### Fan aktualisieren

`PATCH /fans/{id}` · `can_chat`

Senden Sie nur, was sich ändert: Alias, Antwortsprache oder Notizen des Fans. Die Antwort ist der aktualisierte Fan.

```bash
curl -X PATCH https://api.lanachat.ai/v1/fans/fan_921 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Likes beach sets, buys at night"}'
```

### Käufe eines Fans auflisten

`GET /fans/{id}/sales` · `can_sales_read`

```bash
curl https://api.lanachat.ai/v1/fans/fan_921/sales \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "sale_id": "sale_8812", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001", "conversation_id": "conv_1001_88231", "stars": 300, "net_cents": 390, "sent_by": "ai", "kind": "offer" }
  ],
  "next_cursor": null
}
```

Eine paginierte Liste von Verkaufsobjekten. Für Summen pro Tag, Link oder Quelle nutzen Sie [stats](https://lanachat.ai/guides/de/api-tracking/).

### Fan-Historie importieren

`POST /fans/import` · `can_fan_import`

Fügt frühere Fans und deren Nachrichten zu Ihren Daten hinzu, z.B. aus einem anderen Tool. Es wird nie eine Nachricht an einen Fan gesendet und nie ein Kauf bestätigt.

```bash
curl -X POST https://api.lanachat.ai/v1/fans/import \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @fans-history.json
```

## Fan-Listen

### Fan-Listen auflisten

`GET /fan-lists` · `can_fan_read`

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

```json
{
  "data": [ { "id": "vip", "name": "VIP" } ],
  "next_cursor": null
}
```

### Liste erstellen

`POST /fan-lists` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Der Name, der auf der Fans-Seite angezeigt wird |

```bash
curl -X POST https://api.lanachat.ai/v1/fan-lists \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Win back"}'
```

Die Antwort ist die neue Liste (`201`).

### Fans hinzufügen oder entfernen

`POST /fan-lists/{id}/members` und `DELETE /fan-lists/{id}/members` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fan_ids` | array of strings | Yes | Die hinzuzufügenden oder zu entfernenden Fans |

```bash
curl -X POST https://api.lanachat.ai/v1/fan-lists/vip/members \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fan_ids": ["fan_921"]}'
```

`DELETE` verwendet denselben Body. Eine unbekannte Liste oder ein unbekannter Fan ergibt `404`.

## Konversationen

### Konversationen auflisten

`GET /conversations` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Nur diese Creatorin |
| `account_id` | string | No | Nur dieser Telegram-Account |
| `state` | string | No | `ai`, `human`, `script` oder `off` |
| `unread` | boolean | No | `true`: nur Konversationen mit ungelesenen Fan-Nachrichten |
| `limit`, `cursor` | number, string | No | [Paginierung](https://lanachat.ai/guides/de/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/conversations?creator_id=cr_lea&unread=true" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "conv_1001_88231", "fan_id": "fan_921", "creator_id": "cr_lea", "account_id": "acc_1001", "state": "ai", "status": { "tag": "active", "reason": null }, "unread": 2, "last_message_at": "2026-10-06T14:02:51Z", "spent": { "stars": 1450, "net_cents": 1885 }, "source_link_id": "lnk_3" }
  ],
  "next_cursor": null
}
```

### Eine Konversation abrufen

`GET /conversations/{id}` · `can_fan_read`

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

Die Antwort ist das Konversationsobjekt; `state` zeigt, wer antwortet.

### Nachrichten lesen

`GET /conversations/{id}/messages` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `translate` | string | No | Sprachcode, z.B. `en`: jede Nachricht erhält eine Übersetzung |
| `limit`, `cursor` | number, string | No | [Paginierung](https://lanachat.ai/guides/de/api-overview/), neueste zuerst |

```bash
curl "https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages?limit=2" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "msg_77120", "from": "creator", "sent_by": "ai", "text": "Made this one this morning…", "media": [ { "id": "med_5521", "locked": true, "stars": 300 } ], "at": "2026-10-06T14:02:51Z" },
    { "id": "msg_77119", "from": "fan", "text": "show me more 😍", "reactions": [], "at": "2026-10-06T14:02:10Z" }
  ],
  "next_cursor": "eyJpZCI6Im1zZ183NzExOCJ9"
}
```

`sent_by` ist `ai`, `human` (mit `member_id`) oder `script`.

### Nachricht senden

`POST /conversations/{id}/messages` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes, or `media` | Der Text, als Creatorin |
| `media` | array | No | Vault-Medien: `id` und `stars`, um es zu diesem Preis gesperrt zu verkaufen |
| `send_at` | string or null | No | ISO 8601-Zeit zur Planung, bis zu 7 Tage im Voraus; `null` sendet sofort |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text": "Only for you, tonight 🔥", "media": [{"id": "med_5522", "stars": 250}], "send_at": null}'
```

```json
{ "id": "msg_77121", "from": "creator", "sent_by": "human", "token_id": "tok_31", "status": "queued", "at": "2026-10-06T14:03:30Z" }
```

- Eine Nachricht, die über die API gesendet wird, zählt als von einer Person gesendet (`sent_by: "human"`, mit dem Token, das sie gesendet hat) und übernimmt die Konversation (`state: "human"`), bis Sie sie freigeben.
- `status` durchläuft `queued`, `sent`, dann `read`; `failed` enthält den Telegram-Grund (z.B. Flood-Wait).
- Mit `send_at` planen Sie die Nachricht (bis zu 7 Tage im Voraus).

### Auf eine Nachricht reagieren

`POST /conversations/{id}/reactions` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `message_id` | string | Yes | Die Nachricht des Fans |
| `emoji` | string | Yes | Die Reaktion |
| `on` | boolean | Yes | `true` fügt sie hinzu, `false` entfernt sie |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/reactions \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "msg_77119", "emoji": "❤️", "on": true}'
```

### Übernehmen

`POST /conversations/{id}/takeover` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/takeover \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "id": "conv_1001_88231", "state": "human", "taken_by": "tok_31", "taken_at": "2026-10-06T14:04:00Z" }
```

Die KI antwortet diesem Fan nicht mehr, bis Sie die Konversation zurückgeben.

### An die KI zurückgeben

`POST /conversations/{id}/release` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/release \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Die Antwort ist die Konversation mit `state: "ai"`. Eine `off`-Konversation aus Sicherheitsgründen kann nicht freigegeben werden (`409`).

### Skript ausführen

`POST /conversations/{id}/script` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `script_id` | string | Yes | Ein Skript derselben Creatorin, siehe [Scripts](https://lanachat.ai/guides/de/api-scripts/) |

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/script \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"script_id": "scr_204"}'
```

Während das Skript läuft, ist der `state` der Konversation `script`.

### Als gelesen markieren

`POST /conversations/{id}/read` · `can_chat`

```bash
curl -X POST https://api.lanachat.ai/v1/conversations/conv_1001_88231/read \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Das `unread` der Konversation wird auf `0` gesetzt.

## Verwandte Artikel

- [LanaChat API: Schnellstart, Authentifizierung und Fehler](https://lanachat.ai/guides/de/api-overview/)
- [Live Convs: lesen, antworten und übernehmen](https://lanachat.ai/guides/de/live-convs/)
- [Fans: Listen, Status und VIPs](https://lanachat.ai/guides/de/fans/)