API: Fans, Konversationen und Nachrichten

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 #

Das Fan-Objekt #

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

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 #

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

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 #

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

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

Das Verkaufsobjekt #

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

Das gleiche Objekt kommt per webhook, Event sale.completed.

Fans #

Fans auflisten #

GET /fans · can_fan_read

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

{
  "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

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.

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

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

{
  "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.

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.

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

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

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

Liste erstellen #

POST /fan-lists · can_chat

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

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

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

{
  "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

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

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

{
  "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

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

{ "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

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

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

{ "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

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

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

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.