API Askora для разработчиков: сообщения, клиенты, события

Ключ

Ключ выдает студия: откройте бота, «Интеграции» → «API Askora» → «Выдать ключ».

Ключ показывается один раз. Потеряли - замените там же, старый перестанет работать. У каждого бота свой ключ.

Ключ дает полный доступ к клиентам бота: храните его на сервере, не в коде сайта или приложения.

Адрес

Адрес: https://botrun.atoms.technology/api/v1/…. Ключ из студии сам знает, чей он бот, поэтому id бота в адресе не нужен.

Если ключ задан вручную в «Секретах» бота (HOOK_KEY), адрес с id бота: https://botrun.atoms.technology/api/v1/bots/<BOT_ID>/…

Каждый запрос - с заголовком Authorization: Bearer <ключ>. Тело - JSON, ответ - JSON.

Клиента указывают одним из полей: client - номер клиента из «Диалогов», chat - id чата в телеграме.

Методы

Время везде - секунды Unix.

GET`/me`

Бот: имя, адрес, подключен ли. Подходит для проверки ключа.

curl "https://botrun.atoms.technology/api/v1/me" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "bot": { "id": "<BOT_ID>", "name": "Студия Лак", "username": "lak_studio_bot", "link": "https://t.me/lak_studio_bot", "live": true, "paused": false } }

POST`/messages`

Написать клиенту от имени бота. Сообщение появится в «Диалогах».

client или chat: кому
text: текст, до 4096 знаков
buttons: до 10 кнопок-ссылок: label до 64 знаков, url с https:// или tg://

curl -X POST "https://botrun.atoms.technology/api/v1/messages" \
  -H "Authorization: Bearer $CHATSY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client": 42, "text": "Ваш заказ готов", "buttons": [{"label": "Оплатить", "url": "https://example.com/pay/318"}]}'

Ответ

{ "ok": true, "message_id": 1842 }

POST`/clients/update`

Переменные, метки и этап клиента. Бот клиенту не пишет. Смена этапа присылает событие stage.

client или chat: кому
vars: переменные: строка, число или да/нет, до 20 за раз
tags: добавить метки
untag: снять метки
stage: id этапа из /stages (по умолчанию new, work, client, lost)

curl -X POST "https://botrun.atoms.technology/api/v1/clients/update" \
  -H "Authorization: Bearer $CHATSY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client": 42, "vars": {"paid": true, "order": "318"}, "tags": ["оплатил"], "stage": "client"}'

Ответ

{ "ok": true, "client": 42, "at": 1791200000, "sent": 0 }

POST`/run`

Запустить шаг бота у клиента: бот напишет этим шагом и пойдет дальше по сценарию.

client или chat: кому
step: id шага из /steps или номер на схеме (12 или №12)
vars: переменные перед шагом, как в /clients/update

curl -X POST "https://botrun.atoms.technology/api/v1/run" \
  -H "Authorization: Bearer $CHATSY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client": 42, "step": "12", "vars": {"order": "318"}}'

Ответ

{ "ok": true, "client": 42, "at": 1791200000, "sent": 1 }

GET`/clients?since=&limit=&vars=1`

Клиенты, свежие сверху.

since: только те, кто писал после этого времени
limit: сколько, по умолчанию 100, до 500
vars=1: с переменными, тогда до 100

curl "https://botrun.atoms.technology/api/v1/clients?limit=50&vars=1" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "clients": [
  { "client": 42, "chat": 123456789, "name": "Анна", "username": "anna", "stage": "new", "tags": ["vip"], "last_at": 1791200000,
    "vars": { "phone": "+79990000000" } }
] }

GET`/clients/<client>`

Один клиент по номеру из «Диалогов», с переменными.

curl "https://botrun.atoms.technology/api/v1/clients/42" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "client": { "client": 42, "chat": 123456789, "name": "Анна", "username": "anna", "stage": "new", "tags": ["vip"], "last_at": 1791200000,
  "vars": { "phone": "+79990000000" } } }

GET`/clients/find?username=|phone=|var=&value=`

Найти клиента. Ищет среди 500 последних, отдает до 20.

username: username в телеграме, можно с @
phone: телефон из переменных клиента, сравниваются последние 10 цифр
var и value: переменная и ее значение, без учета регистра

curl "https://botrun.atoms.technology/api/v1/clients/find?phone=%2B79990000000" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "clients": [{ "client": 42, "chat": 123456789, "name": "Анна", "username": "anna", "stage": "new", "tags": ["vip"], "last_at": 1791200000, "vars": { "phone": "+79990000000" } }] }

GET`/stages`

Этапы бота: id для поля stage.

curl "https://botrun.atoms.technology/api/v1/stages" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "stages": [{ "id": "new", "name": "Новый" }, { "id": "work", "name": "В работе" }, { "id": "client", "name": "Клиент" }] }

GET`/steps`

Шаги бота: id для поля step в /run. start - первый шаг.

curl "https://botrun.atoms.technology/api/v1/steps" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "steps": [{ "id": "start", "title": "Здравствуйте! Я помогу записаться", "start": true }, { "id": "b12", "title": "Выберите услугу", "start": false }] }

GET`/leads?since=&limit=`

Заявки, записи и вопросы, свежие сверху. Для опроса, если подписки нет.

since: только новее этого времени
limit: сколько, по умолчанию 50, до 500

curl "https://botrun.atoms.technology/api/v1/leads?since=1791100000" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "leads": [
  { "id": 318, "at": 1791200000, "kind": "lead", "title": "Заявка", "status": "new", "client": "Анна", "username": "anna",
    "what": "Маникюр, завтра", "details": [{ "q": "Услуга", "a": "Маникюр" }], "chat": 123456789 }
] }

GET`/hooks`

Подписки на события.

curl "https://botrun.atoms.technology/api/v1/hooks" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "hooks": [{ "id": 7, "url": "https://example.com/askora", "events": ["lead", "message"], "createdAt": 1791200000 }] }

POST`/hooks`

Подписаться: события придут POST-запросом на ваш адрес.

url: адрес https
events: какие события, список ниже

curl -X POST "https://botrun.atoms.technology/api/v1/hooks" \
  -H "Authorization: Bearer $CHATSY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/askora", "events": ["lead", "message"]}'

Ответ

{ "hook": { "id": 7, "url": "https://example.com/askora", "events": ["lead", "message"] } }

DELETE`/hooks/<id>`

Отписаться.

curl -X DELETE "https://botrun.atoms.technology/api/v1/hooks/7" \
  -H "Authorization: Bearer $CHATSY_KEY"

Ответ

{ "ok": true }

Ошибки

Ошибка приходит с кодом HTTP и телом { "error": "код" }.

КодHTTPЧто случилось

api_off401у бота нет ключа: выдайте его в студии

bad_key401ключ неверный, заменен или не указан

not_found404нет такого бота, адреса или подписки

disconnected409бот не подключен к телеграму

no_client400не указан client или chat

no_query400в /clients/find не указано, что искать

unknown_client404клиент не писал этому боту

bad_text400текст пустой или длиннее 4096 знаков

bad_buttons400у кнопки нет названия или адрес не https:// или tg://

no_step400в /run не указан step

bad_step400такого шага нет на схеме

bad_var:<имя>400имя переменной пустое или слишком длинное

bad_value:<имя>400значение переменной не строка, не число и не да/нет

bad_stage400у бота нет такого этапа

busy409клиент в эту секунду отвечает боту: повторите запрос

bad_url400адрес подписки не https

bad_events400в подписке нет известных событий

too_many409уже 20 подписок: удалите ненужную

telegram502телеграм не принял сообщение, например клиент остановил бота

rate_limited429больше 120 запросов в минуту: подождите

События

Подписка получает событие сразу, как оно случилось. Тело - JSON, тот же, что у вебхука бота.

lead новая заявка или запись
question вопрос клиента
client новый клиент написал боту
message сообщение клиента
stage сменился этап клиента
tags сменились метки клиента
blocked клиент остановил бота

Во всех событиях подписок chat_id - чат клиента и client_number - его номер из «Диалогов»: по любому из них можно сразу ответить через /messages. У message в data kind (text - текст, press - нажатие кнопки) и text, у client - start, у stage - from и to, у tags - added и removed. У lead и question вместо data - what и details (вопросы и ответы клиента). Примеры - message и lead:

{
  "bot": { "id": "<BOT_ID>", "username": "lak_studio_bot", "name": "Студия Лак" },
  "event": {
    "kind": "message", "kind_label": "Сообщение клиента",
    "at": 1791200000, "at_iso": "2026-10-05T09:00:00.000Z",
    "chat_id": 123456789, "client_number": 12, "client": "Анна", "username": "anna",
    "data": { "kind": "text", "text": "Здравствуйте! Есть время на завтра?" }
  }
}

{
  "bot": { "id": "<BOT_ID>", "username": "lak_studio_bot", "name": "Студия Лак" },
  "event": {
    "kind": "lead", "kind_label": "Заявка",
    "at": 1791200000, "at_iso": "2026-10-05T09:00:00.000Z",
    "client": "Анна", "username": "anna", "chat_id": 123456789, "client_number": 12,
    "what": "Маникюр, завтра",
    "details": [{ "q": "Услуга", "a": "Маникюр" }, { "q": "Когда удобно", "a": "завтра" }]
  }
}

Если у бота задан секрет WEBHOOK_SECRET («Интеграции» → «Вебхук»), каждое событие приходит с заголовком x-rilmo-signature: sha256=<HMAC-SHA256 тела этим секретом в hex>.

Проверяйте подпись по телу как оно пришло, до разбора JSON:

import crypto from "node:crypto";

// raw - тело запроса как есть, до JSON.parse
const sig = "sha256=" + crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(raw).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers["x-rilmo-signature"] ?? ""));

Пределы

120 запросов в минуту с одного IP.
Текст сообщения до 4096 знаков, до 10 кнопок.
До 20 подписок на бота.
Клиенты - до 500 за запрос, с переменными до 100. Заявки - до 500. Поиск - до 20 среди 500 последних клиентов.

Make, n8n, Albato

Make и n8n: модуль HTTP: адрес метода, заголовок Authorization: Bearer <ключ>, тело JSON. События - вебхук Make или n8n в POST /hooks.

Albato: приложение Askora в каталоге Albato готовим. Пока подойдет HTTP-запрос и вебхук Albato так же, как в Make.

API Askora.Бот из вашего сайта, CRM и Albato.

Ключ

Адрес

Методы

GET/me

POST/messages

POST/clients/update

POST/run

GET/clients?since=&limit=&vars=1

GET/clients/<client>

GET/clients/find?username=|phone=|var=&value=

GET/stages

GET/steps

GET/leads?since=&limit=

GET/hooks

POST/hooks

DELETE/hooks/<id>

Ошибки

События

Пределы

Make, n8n, Albato

API Askora.
Бот из вашего сайта, CRM и Albato.

GET`/me`

POST`/messages`

POST`/clients/update`

POST`/run`

GET`/clients?since=&limit=&vars=1`

GET`/clients/<client>`

GET`/clients/find?username=|phone=|var=&value=`

GET`/stages`

GET`/steps`

GET`/leads?since=&limit=`

GET`/hooks`

POST`/hooks`

DELETE`/hooks/<id>`