API: fani, conversații și mesaje

Un fan este un utilizator Telegram care a scris uneia dintre creatoarele tale. O conversație este chatul dintre acel fan și un cont Telegram. Mesajele sunt trimise de AI, de un coleg sau de un script. Aceste endpointuri corespund cu Live Convs și Fans din Console.

Endpoints #

Obiectul fan #

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

Un fan are și limbile în care scrie, tagul de status, notițele echipei, un alias și limba de răspuns, ca pe pagina Fans.

Obiectul conversație #

{
  "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 corespunde tagurilor de status de pe pagina Fans (review, safety_hold, converted, lost, underage…). O conversație off din motive de siguranță nu poate fi dată înapoi la AI (409).

Obiectul mesaj #

{
  "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 stabilește comisionul unei vânzări, deci este setat de server și nu de cererea ta.

Obiectul vânzare #

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

Același obiect vine prin webhook, evenimentul sale.completed.

Fani #

Listează fanii #

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
}

Obține un fan #

GET /fans/{id} · can_fan_read

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

Răspunsul este obiectul fan. Un id necunoscut răspunde cu 404.

Actualizează un fan #

PATCH /fans/{id} · can_chat

Trimite doar ce se schimbă: aliasul fanului, limba de răspuns sau notițele. Răspunsul este fanul actualizat.

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

Listează achizițiile unui fan #

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
}

O listă paginată de obiecte vânzare. Pentru totaluri pe zi, link sau sursă, folosește stats.

Importează istoricul fanilor #

POST /fans/import · can_fan_import

Adaugă fani din trecut și mesajele lor în baza ta, de exemplu din altă unealtă. Nu trimite niciodată mesaje fanilor și nu confirmă vreo achiziție.

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

Liste de fani #

Listează listele de fani #

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
}

Creează o listă #

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

Răspunsul este noua listă (201).

Adaugă sau elimină fani #

POST /fan-lists/{id}/members și 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 folosește același body. O listă sau un fan necunoscut răspunde cu 404.

Conversații #

Listează conversațiile #

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
}

Obține o conversație #

GET /conversations/{id} · can_fan_read

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

Răspunsul este obiectul conversație; state arată cine răspunde.

Citește mesajele #

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 poate fi ai, human (cu member_id) sau script.

Trimite un mesaj #

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

• Un mesaj trimis prin API este considerat trimis de o persoană (sent_by: "human", cu tokenul care l-a trimis) și preia conversația (state: "human") până o eliberezi.
• status trece prin queued, sent, apoi read; failed conține motivul Telegram (de exemplu flood wait).
• send_at programează mesajul (maxim 7 zile în avans).

Reacționează la un mesaj #

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

Preia conversația #

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

AI-ul nu mai răspunde acestui fan până când dai conversația înapoi.

Dă conversația înapoi la AI #

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

Răspunsul este conversația cu state: "ai". O conversație off din motive de siguranță nu poate fi eliberată (409).

Rulează un script #

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

Cât timp rulează, state al conversației este script.

Marchează ca citit #

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

unread al conversației revine la 0.