# API: фанати, діалоги та повідомлення

_API · Читання 7 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/api-conversations/_

**Fan**, це користувач Telegram, який написав одній з ваших авторок. **Conversation**, це чат між цим фанатом і одним Telegram-акаунтом. Повідомлення надсилає AI, член команди або скрипт. Ці endpoints відповідають розділам **Live Convs** і **Fans** у Console.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/fans` | Список фанатів (`creator_id=`, `status=`, `list_id=`, `q=`, `spent_min=`) | `can_fan_read` | Planned |
| GET | `/fans/{id}` | Один фанат: мови, витрати, статус, списки, нотатки | `can_fan_read` | Planned |
| PATCH | `/fans/{id}` | Змінити псевдонім, мову відповіді або нотатки фаната | `can_chat` | Planned |
| GET | `/fans/{id}/sales` | Покупки фаната | `can_sales_read` | Planned |
| POST | `/fans/import` | Імпорт минулих фанатів і повідомлень (нічого не надсилає) | `can_fan_import` | Planned |
| GET | `/fan-lists` | Списки (VIP, win back…) | `can_fan_read` | Planned |
| POST | `/fan-lists` | Створити список | `can_chat` | Planned |
| POST | `/fan-lists/{id}/members` | Додати фанатів до списку | `can_chat` | Planned |
| DELETE | `/fan-lists/{id}/members` | Видалити фанатів зі списку | `can_chat` | Planned |
| GET | `/conversations` | Список діалогів (`creator_id=`, `account_id=`, `state=`, `unread=true`) | `can_fan_read` | Planned |
| GET | `/conversations/{id}` | Один діалог і хто відповідає | `can_fan_read` | Planned |
| GET | `/conversations/{id}/messages` | Повідомлення, спочатку нові (`translate=en` додає переклад) | `can_fan_read` | Planned |
| POST | `/conversations/{id}/messages` | Надіслати повідомлення як авторка (текст, медіа, offer) | `can_chat` | Planned |
| POST | `/conversations/{id}/reactions` | Додати або прибрати реакцію на повідомлення фаната | `can_chat` | Planned |
| POST | `/conversations/{id}/takeover` | Людина бере діалог: AI перестає відповідати цьому фанату | `can_chat` | Planned |
| POST | `/conversations/{id}/release` | Повернути діалог AI | `can_chat` | Planned |
| POST | `/conversations/{id}/script` | Запустити скрипт у цьому діалозі | `can_chat` | Planned |
| POST | `/conversations/{id}/read` | Позначити діалог як прочитаний | `can_chat` | Planned |

## The fan object

```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 | Починається з `fan_` |
| `display_name` | string | Ім'я фаната у Telegram |
| `username` | string or null | Telegram @username фаната, без @ |
| `creator_id` | string | Авторка, якій написав цей фанат |
| `purchases` | number | Підтверджені покупки |
| `spent` | object | Всього витрачено: `stars` і `net_cents` у центах США після комісії Telegram і повернень |
| `lists` | array of strings | Id списків фаната, у яких він знаходиться |

Фанат також має мови, якими пише, статус, нотатки команди, псевдонім і мову відповіді, як на сторінці **Fans**.

## The conversation object

```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 | Починається з `conv_` |
| `fan_id`, `creator_id`, `account_id` | string | Хто з ким спілкується, у якому Telegram-акаунті |
| `state` | string | Хто відповідає: `ai`, `human` (перехоплено), `script` (йде скрипт) або `off` |
| `status` | object | `tag` (статус зі сторінки Fans) і `reason`, якщо є |
| `unread` | number | Непрочитані повідомлення фаната |
| `last_message_at` | string | ISO 8601, UTC |
| `spent` | object | Скільки фанат витратив у цьому діалозі: `stars` і `net_cents` |
| `source_link_id` | string or null | Трекінгове посилання, з якого прийшов фанат |

`status.tag` відповідає статусам зі сторінки Fans (`review`, `safety_hold`, `converted`, `lost`, `underage`…). Діалог у стані `off` з причин безпеки не можна повернути AI (`409`).

## The message object

```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 | Починається з `msg_` |
| `from` | string | `creator` або `fan` |
| `sent_by` | string | Для повідомлень авторки: `ai`, `human` або `script` |
| `member_id` | string | Хто з команди надіслав, якщо `sent_by`, `human` з Console |
| `token_id` | string | Токен доступу, який надіслав, якщо з API |
| `text` | string | Текст повідомлення |
| `media` | array | Медіа: `id`, `locked` (платне і ще не куплене) і ціна у `stars` |
| `reactions` | array | Реакції на повідомлення фаната |
| `status` | string | Для ваших повідомлень: `queued`, `sent`, `read` або `failed` |
| `at` | string | ISO 8601, UTC |

`sent_by` визначає комісію з продажу, тому встановлюється сервером і не залежить від вашого запиту.

## The sale object

```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 | Починається з `sale_` |
| `fan_id`, `creator_id`, `account_id`, `conversation_id` | string | Хто купив, у кого, де |
| `stars` | number | Сума у Telegram Stars |
| `net_cents` | number | Чиста сума у центах США (1 Star = $0.013) |
| `sent_by` | string | `ai`, `human` або `script`: хто надіслав offer, це впливає на комісію |
| `kind` | string | Що купили, наприклад `offer` |

Такий самий об'єкт приходить через [webhook](https://lanachat.ai/guides/uk/api-webhooks/), подія `sale.completed`.

## Fans

### List fans

`GET /fans` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Тільки фанати цієї авторки |
| `status` | string | No | Статус зі сторінки Fans, наприклад `converted` |
| `list_id` | string | No | Тільки фанати цього списку |
| `q` | string | No | Частина імені або username фаната |
| `spent_min` | number | No | Тільки фанати, які витратили не менше стількох Stars |
| `limit`, `cursor` | number, string | No | [Пагінація](https://lanachat.ai/guides/uk/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
}
```

### Get a fan

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

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

Відповідь, це fan object. Якщо id невідомий, `404`.

### Update a fan

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

Надсилайте лише те, що змінюється: псевдонім, мову відповіді або нотатки фаната. Відповідь, оновлений фанат.

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

### List a fan's purchases

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

Посторінковий список sale objects. Для підсумків по днях, посиланнях чи джерелах використовуйте [stats](https://lanachat.ai/guides/uk/api-tracking/).

### Import fan history

`POST /fans/import` · `can_fan_import`

Додає минулих фанатів і їхні повідомлення у ваші записи, наприклад з іншого інструменту. Ніколи не надсилає повідомлення фанату і не підтверджує покупку.

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

### List fan lists

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

### Create a list

`POST /fan-lists` · `can_chat`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Назва, яка відображається на сторінці 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"}'
```

Відповідь, новий список (`201`).

### Add or remove fans

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `fan_ids` | array of strings | Yes | Фанати для додавання або видалення |

```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` приймає такий самий body. Якщо список або фанат невідомі, `404`.

## Conversations

### List conversations

`GET /conversations` · `can_fan_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Тільки ця авторка |
| `account_id` | string | No | Тільки цей Telegram-акаунт |
| `state` | string | No | `ai`, `human`, `script` або `off` |
| `unread` | boolean | No | `true`: тільки діалоги з непрочитаними повідомленнями фаната |
| `limit`, `cursor` | number, string | No | [Пагінація](https://lanachat.ai/guides/uk/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
}
```

### Get a conversation

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

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

Відповідь, conversation object; `state` показує, хто відповідає.

### Read messages

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `translate` | string | No | Код мови, наприклад `en`: кожне повідомлення також отримує переклад |
| `limit`, `cursor` | number, string | No | [Пагінація](https://lanachat.ai/guides/uk/api-overview/), спочатку нові |

```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`, це `ai`, `human` (з `member_id`) або `script`.

### Send a message

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes, or `media` | Текст, як авторка |
| `media` | array | No | Vault media: `id` і `stars` для продажу заблокованого медіа за цю ціну |
| `send_at` | string or null | No | Час у ISO 8601 для відкладеної відправки (до 7 днів); `null`, надіслати зараз |

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

- Повідомлення, надіслане через API, вважається надісланим людиною (`sent_by: "human"`, з токеном, який його надіслав) і переводить діалог у стан `state: "human"` до повернення.
- `status` змінюється: `queued`, `sent`, потім `read`; `failed` містить причину від Telegram (наприклад flood wait).
- `send_at` дозволяє запланувати повідомлення (до 7 днів наперед).

### React to a message

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `message_id` | string | Yes | Повідомлення фаната |
| `emoji` | string | Yes | Реакція |
| `on` | boolean | Yes | `true`, додати, `false`, прибрати |

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

### Take over

`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 перестає відповідати цьому фанату, поки ви не повернете діалог.

### Give back to the 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)"
```

Відповідь, діалог зі `state: "ai"`. Діалог у стані `off` з причин безпеки не можна повернути (`409`).

### Run a script

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `script_id` | string | Yes | Скрипт цієї ж авторки, див. [Scripts](https://lanachat.ai/guides/uk/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"}'
```

Поки скрипт виконується, `state` діалогу, `script`.

### Mark as read

`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` діалогу повертається до `0`.

## Пов’язані статті

- [LanaChat API: швидкий старт, автентифікація та помилки](https://lanachat.ai/guides/uk/api-overview/)
- [Live Convs: читати, відповідати та брати контроль](https://lanachat.ai/guides/uk/live-convs/)
- [Фанати: списки, статуси та VIP](https://lanachat.ai/guides/uk/fans/)