API reference

Fans and conversations API

A fan is a Telegram user who wrote to one of your creators. A conversation is the chat between that fan and one Telegram account. Messages are sent by the AI, by a teammate or by a script. These endpoints match Live Convs and Fans in the Console.

Planned

Every endpoint on this page is marked Planned: it is the published contract the backend is built from, and it does not answer yet.

Endpoints #

Method	Path	Description	Permission	Status
GET	`/fans`	List fans (`creator_id=`, `status=`, `list_id=`, `q=`, `spent_min=`)	`can_fan_read`	Planned
GET	`/fans/{id}`	One fan: languages, spend, status, lists, notes	`can_fan_read`	Planned
PATCH	`/fans/{id}`	Change the fan's alias, reply language or notes	`can_chat`	Planned
GET	`/fans/{id}/sales`	The fan's purchases	`can_sales_read`	Planned
POST	`/fans/import`	Import past fans and messages (never sends anything)	`can_fan_import`	Planned
GET	`/fan-lists`	Lists (VIPs, win back…)	`can_fan_read`	Planned
POST	`/fan-lists`	Create a list	`can_chat`	Planned
POST	`/fan-lists/{id}/members`	Add fans to a list	`can_chat`	Planned
DELETE	`/fan-lists/{id}/members`	Remove fans from a list	`can_chat`	Planned
GET	`/conversations`	List conversations (`creator_id=`, `account_id=`, `state=`, `unread=true`)	`can_fan_read`	Planned
GET	`/conversations/{id}`	One conversation and who is replying	`can_fan_read`	Planned
GET	`/conversations/{id}/messages`	Messages, newest first (`translate=en` adds a translation)	`can_fan_read`	Planned
POST	`/conversations/{id}/messages`	Send a message as the creator (text, media, offer)	`can_chat`	Planned
POST	`/conversations/{id}/reactions`	Add or remove a reaction on a fan's message	`can_chat`	Planned
POST	`/conversations/{id}/takeover`	A person takes over: the AI stops answering this fan	`can_chat`	Planned
POST	`/conversations/{id}/release`	Give the conversation back to the AI	`can_chat`	Planned
POST	`/conversations/{id}/script`	Run a script on this conversation	`can_chat`	Planned
POST	`/conversations/{id}/read`	Mark the conversation as 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	Starts with `fan_`
`display_name`	string	The fan's name on Telegram
`username`	string or null	The fan's Telegram @username, without the @
`creator_id`	string	The creator this fan wrote to
`purchases`	number	Verified purchases so far
`spent`	object	Total spent: `stars`, and `net_cents` in US cents after Telegram's share and refunds
`lists`	array of strings	Ids of the fan lists this fan is in

A fan also carries the languages they write in, their status tag, the team's notes, an alias and a reply language, as on the Fans page.

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	Starts with `conv_`
`fan_id`, `creator_id`, `account_id`	string	Who talks to whom, on which Telegram account
`state`	string	Who replies: `ai`, `human` (taken over), `script` (a script is running) or `off`
`status`	object	`tag` (the status tags of the Fans page) and the `reason` when there is one
`unread`	number	Fan messages not read yet
`last_message_at`	string	ISO 8601, UTC
`spent`	object	What the fan spent in this conversation: `stars` and `net_cents`
`source_link_id`	string or null	The tracking link the fan came from

status.tag matches the status tags of the Fans page (review, safety_hold, converted, lost, underage…). An off conversation for a safety reason cannot be released to the 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	Starts with `msg_`
`from`	string	`creator` or `fan`
`sent_by`	string	For creator messages: `ai`, `human` or `script`
`member_id`	string	The teammate who sent it, when `sent_by` is `human` from the Console
`token_id`	string	The access token that sent it, when it came from the API
`text`	string	The text of the message
`media`	array	Media sent: `id`, `locked` (paid and not bought yet) and its price in `stars`
`reactions`	array	Reactions on a fan message
`status`	string	For messages you send: `queued`, `sent`, `read` or `failed`
`at`	string	ISO 8601, UTC

sent_by decides the commission rate of a sale, so it is set by the server and never by your request.

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	Starts with `sale_`
`fan_id`, `creator_id`, `account_id`, `conversation_id`	string	Who bought, from whom, where
`stars`	number	Price paid in Telegram Stars
`net_cents`	number	Net value in US cents (a Star counts $0.013)
`sent_by`	string	`ai`, `human` or `script`: who sent the offer, it sets the commission rate
`kind`	string	What was bought, for example `offer`

The same object arrives by webhook, event sale.completed.

Fans #

List fans #

GET/fansPlannedNeeds can_fan_read

Parameter	Type	Required	Description
`creator_id`	string	No	Only the fans of this creator
`status`	string	No	A status tag of the Fans page, for example `converted`
`list_id`	string	No	Only the fans of this list
`q`	string	No	Part of the fan's name or username
`spent_min`	number	No	Only fans who spent at least this many Stars
`limit`, `cursor`	number, string	No	Pagination

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

const res = await fetch('https://api.lanachat.ai/v1/fans?creator_id=cr_lea&spent_min=1000&limit=50', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/fans?creator_id=cr_lea&spent_min=1000&limit=50",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

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

const res = await fetch('https://api.lanachat.ai/v1/fans/fan_921', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/fans/fan_921",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The answer is the fan object. An unknown id answers 404.

Update a fan #

PATCH/fans/{id}PlannedNeeds can_chat

Send only what changes: the fan's alias, reply language or notes. The answer is the updated 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"}'

const res = await fetch('https://api.lanachat.ai/v1/fans/fan_921', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ notes: 'Likes beach sets, buys at night' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.patch(
    "https://api.lanachat.ai/v1/fans/fan_921",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    json={"notes": "Likes beach sets, buys at night"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

List a fan's purchases #

GET/fans/{id}/salesPlannedNeeds can_sales_read

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

const res = await fetch('https://api.lanachat.ai/v1/fans/fan_921/sales', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/fans/fan_921/sales",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

A paged list of sale objects. For totals per day, link or source, use stats.

Import fan history #

POST/fans/importPlannedNeeds can_fan_import

Adds past fans and their messages to your records, for example from another tool. It never sends a message to a fan and never confirms a purchase.

cURL

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-listsPlannedNeeds can_fan_read

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

const res = await fetch('https://api.lanachat.ai/v1/fan-lists', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/fan-lists",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

Create a list #

POST/fan-listsPlannedNeeds can_chat

Parameter	Type	Required	Description
`name`	string	Yes	The name shown on the Fans page

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

const res = await fetch('https://api.lanachat.ai/v1/fan-lists', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Win back' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/fan-lists",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"name": "Win back"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

The answer is the new list (201).

Add or remove fans #

POST/fan-lists/{id}/membersPlannedDELETE/fan-lists/{id}/membersPlannedNeeds can_chat

Parameter	Type	Required	Description
`fan_ids`	array of strings	Yes	The fans to add or remove

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

const res = await fetch('https://api.lanachat.ai/v1/fan-lists/vip/members', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fan_ids: ['fan_921'] }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/fan-lists/vip/members",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"fan_ids": ["fan_921"]},
    timeout=30,
)
r.raise_for_status()
print(r.json())

DELETE takes the same body. An unknown list or fan answers 404.

Conversations #

List conversations #

GET/conversationsPlannedNeeds can_fan_read

Parameter	Type	Required	Description
`creator_id`	string	No	Only this creator
`account_id`	string	No	Only this Telegram account
`state`	string	No	`ai`, `human`, `script` or `off`
`unread`	boolean	No	`true`: only conversations with unread fan messages
`limit`, `cursor`	number, string	No	Pagination

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

const res = await fetch('https://api.lanachat.ai/v1/conversations?creator_id=cr_lea&unread=true', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/conversations?creator_id=cr_lea&unread=true",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The answer is the conversation object; state says who is replying.

Read messages #

GET/conversations/{id}/messagesPlannedNeeds can_fan_read

Parameter	Type	Required	Description
`translate`	string	No	A language code, for example `en`: each message also gets a translation
`limit`, `cursor`	number, string	No	Pagination, newest first

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages?limit=2', {
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages?limit=2",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

{
  "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 is ai, human (with member_id) or script.

Send a message #

POST/conversations/{id}/messagesPlannedNeeds can_chat

Parameter	Type	Required	Description
`text`	string	Yes, or `media`	The text, as the creator
`media`	array	No	Vault media: `id`, and `stars` to sell it locked at that price
`send_at`	string or null	No	ISO 8601 time to schedule it, up to 7 days ahead; `null` sends now

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Only for you, tonight 🔥', media: [{ id: 'med_5522', stars: 250 }], send_at: null }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/messages",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "text": "Only for you, tonight 🔥",
        "media": [{"id": "med_5522", "stars": 250}],
        "send_at": None,
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

A message sent through the API counts as sent by a person (sent_by: "human", with the token that sent it) and takes the conversation over (state: "human") until you release it.
status goes queued, sent, then read; failed carries the Telegram reason (for example a flood wait).
send_at schedules the message (up to 7 days ahead).

React to a message #

POST/conversations/{id}/reactionsPlannedNeeds can_chat

Parameter	Type	Required	Description
`message_id`	string	Yes	The fan's message
`emoji`	string	Yes	The reaction
`on`	boolean	Yes	`true` adds it, `false` removes it

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/reactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message_id: 'msg_77119', emoji: '❤️', on: true }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/reactions",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"message_id": "msg_77119", "emoji": "❤️", "on": True},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Take over #

POST/conversations/{id}/takeoverPlannedNeeds can_chat

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/takeover', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/takeover",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

Response

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

The AI stops answering this fan until you give the conversation back.

Give back to the AI #

POST/conversations/{id}/releasePlannedNeeds can_chat

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/release', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/release",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The answer is the conversation with state: "ai". An off conversation for a safety reason cannot be released (409).

Run a script #

POST/conversations/{id}/scriptPlannedNeeds can_chat

Parameter	Type	Required	Description
`script_id`	string	Yes	A script of the same creator, see Scripts

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/script', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ script_id: 'scr_204' }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/script",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"script_id": "scr_204"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

While it runs, the conversation's state is script.

Mark as read #

POST/conversations/{id}/readPlannedNeeds can_chat

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

const res = await fetch('https://api.lanachat.ai/v1/conversations/conv_1001_88231/read', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

import os
import uuid
import requests

r = requests.post(
    "https://api.lanachat.ai/v1/conversations/conv_1001_88231/read",
    headers={
        "Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The conversation's unread goes back to 0.

Errors #

Every endpoint answers errors in the same JSON body, {"error": {"code": "…", "message": "…"}}, with the common codes 400, 401, 402, 403, 404, 409, 429 and 500 listed in Errors. What the endpoints of this page say they answer:

Endpoint	Status	When
Get a fan	`404`	An unknown id answers `404`.
Add or remove fans	`404`	An unknown list or fan answers `404`.
Give back to the AI	`409`	An `off` conversation for a safety reason cannot be released (`409`).

Tutorial: API: fans, conversations and messages