# API: fani, conversații și mesaje

_API · 7 min de citit · Actualizat 2026-10-22 · https://lanachat.ai/guides/ro/api-conversations/_

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

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/fans` | Listează fanii (`creator_id=`, `status=`, `list_id=`, `q=`, `spent_min=`) | `can_fan_read` | Planned |
| GET | `/fans/{id}` | Un fan: limbi, cheltuieli, status, liste, notițe | `can_fan_read` | Planned |
| PATCH | `/fans/{id}` | Schimbă aliasul fanului, limba de răspuns sau notițele | `can_chat` | Planned |
| GET | `/fans/{id}/sales` | Achizițiile fanului | `can_sales_read` | Planned |
| POST | `/fans/import` | Importează fani și mesaje din trecut (nu trimite niciodată nimic) | `can_fan_import` | Planned |
| GET | `/fan-lists` | Liste (VIP, win back…) | `can_fan_read` | Planned |
| POST | `/fan-lists` | Creează o listă | `can_chat` | Planned |
| POST | `/fan-lists/{id}/members` | Adaugă fani într-o listă | `can_chat` | Planned |
| DELETE | `/fan-lists/{id}/members` | Elimină fani dintr-o listă | `can_chat` | Planned |
| GET | `/conversations` | Listează conversațiile (`creator_id=`, `account_id=`, `state=`, `unread=true`) | `can_fan_read` | Planned |
| GET | `/conversations/{id}` | O conversație și cine răspunde | `can_fan_read` | Planned |
| GET | `/conversations/{id}/messages` | Mesaje, cele mai noi primele (`translate=en` adaugă traducere) | `can_fan_read` | Planned |
| POST | `/conversations/{id}/messages` | Trimite un mesaj ca și creator (text, media, ofertă) | `can_chat` | Planned |
| POST | `/conversations/{id}/reactions` | Adaugă sau elimină o reacție la mesajul unui fan | `can_chat` | Planned |
| POST | `/conversations/{id}/takeover` | O persoană preia: AI-ul nu mai răspunde acestui fan | `can_chat` | Planned |
| POST | `/conversations/{id}/release` | Dă conversația înapoi la AI | `can_chat` | Planned |
| POST | `/conversations/{id}/script` | Rulează un script pe această conversație | `can_chat` | Planned |
| POST | `/conversations/{id}/read` | Marchează conversația ca citită | `can_chat` | Planned |

## Obiectul fan

```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 | Începe cu `fan_` |
| `display_name` | string | Numele fanului pe Telegram |
| `username` | string sau null | @username-ul fanului pe Telegram, fără @ |
| `creator_id` | string | Creatoarea căreia i-a scris acest fan |
| `purchases` | number | Achiziții verificate până acum |
| `spent` | object | Total cheltuit: `stars` și `net_cents` în cenți SUA după comisionul Telegram și refunduri |
| `lists` | array of strings | ID-urile listelor de fani în care se află acest fan |

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

```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 | Începe cu `conv_` |
| `fan_id`, `creator_id`, `account_id` | string | Cine vorbește cu cine, pe ce cont Telegram |
| `state` | string | Cine răspunde: `ai`, `human` (preluat), `script` (rulează un script) sau `off` |
| `status` | object | `tag` (tagurile de status de pe pagina Fans) și `reason` dacă există |
| `unread` | number | Mesaje de la fan necitite încă |
| `last_message_at` | string | ISO 8601, UTC |
| `spent` | object | Cât a cheltuit fanul în această conversație: `stars` și `net_cents` |
| `source_link_id` | string sau null | Linkul de tracking de unde a venit fanul |

`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

```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 | Începe cu `msg_` |
| `from` | string | `creator` sau `fan` |
| `sent_by` | string | Pentru mesajele creatoarei: `ai`, `human` sau `script` |
| `member_id` | string | Colegul care a trimis, când `sent_by` este `human` din Console |
| `token_id` | string | Tokenul de acces care a trimis, când vine din API |
| `text` | string | Textul mesajului |
| `media` | array | Media trimisă: `id`, `locked` (plătită și încă nebought) și prețul în `stars` |
| `reactions` | array | Reacții la un mesaj de fan |
| `status` | string | Pentru mesajele trimise: `queued`, `sent`, `read` sau `failed` |
| `at` | string | ISO 8601, UTC |

`sent_by` stabilește comisionul unei vânzări, deci este setat de server și nu de cererea ta.

## Obiectul vânzare

```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 | Începe cu `sale_` |
| `fan_id`, `creator_id`, `account_id`, `conversation_id` | string | Cine a cumpărat, de la cine, unde |
| `stars` | number | Prețul plătit în Telegram Stars |
| `net_cents` | number | Valoarea netă în cenți SUA (un Star valorează $0.013) |
| `sent_by` | string | `ai`, `human` sau `script`: cine a trimis oferta, stabilește comisionul |
| `kind` | string | Ce s-a cumpărat, de exemplu `offer` |

Același obiect vine prin [webhook](https://lanachat.ai/guides/ro/api-webhooks/), evenimentul `sale.completed`.

## Fani

### Listează fanii

`GET /fans` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Nu | Doar fanii acestei creatoare |
| `status` | string | Nu | Un tag de status de pe pagina Fans, de exemplu `converted` |
| `list_id` | string | Nu | Doar fanii acestei liste |
| `q` | string | Nu | Parte din numele sau username-ul fanului |
| `spent_min` | number | Nu | Doar fanii care au cheltuit cel puțin atâția Stars |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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
}
```

### Obține un fan

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

```bash
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.

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

### Listează achizițiile unui fan

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

O listă paginată de obiecte vânzare. Pentru totaluri pe zi, link sau sursă, folosește [stats](https://lanachat.ai/guides/ro/api-tracking/).

### 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.

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

## Liste de fani

### Listează listele de fani

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

### Creează o listă

`POST /fan-lists` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Da | Numele afișat pe pagina Fans |

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

Răspunsul este noua listă (`201`).

### Adaugă sau elimină fani

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fan_ids` | array of strings | Da | Fanii de adăugat sau eliminat |

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | Nu | Doar această creatoare |
| `account_id` | string | Nu | Doar acest cont Telegram |
| `state` | string | Nu | `ai`, `human`, `script` sau `off` |
| `unread` | boolean | Nu | `true`: doar conversațiile cu mesaje necitite de la fani |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/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
}
```

### Obține o conversație

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

```bash
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`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `translate` | string | Nu | Un cod de limbă, de exemplu `en`: fiecare mesaj primește și traducere |
| `limit`, `cursor` | number, string | Nu | [Paginare](https://lanachat.ai/guides/ro/api-overview/), cele mai noi primele |

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

### Trimite un mesaj

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Da, sau `media` | Textul, ca și creatoare |
| `media` | array | Nu | Media din Vault: `id` și `stars` pentru a o vinde blocată la acel preț |
| `send_at` | string sau null | Nu | Ora ISO 8601 pentru programare, maxim 7 zile în avans; `null` trimite acum |

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

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `message_id` | string | Da | Mesajul fanului |
| `emoji` | string | Da | Reacția |
| `on` | boolean | Da | `true` o adaugă, `false` o elimină |

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

### Preia conversația

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

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`

```bash
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`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `script_id` | string | Da | Un script al aceleiași creatoare, vezi [Scripts](https://lanachat.ai/guides/ro/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"}'
```

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

### Marchează ca citit

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

`unread` al conversației revine la `0`.

## Articole conexe

- [API LanaChat: început rapid, autentificare și erori](https://lanachat.ai/guides/ro/api-overview/)
- [Live Convs: citește, răspunde și preia conversația](https://lanachat.ai/guides/ro/live-convs/)
- [Fans: liste, stări și VIP-uri](https://lanachat.ai/guides/ro/fans/)