API и подключение ИИ

Полный доступ к воркспейсу по API-ключу: создавайте и настраивайте ботов, управляйте каналами, рассылками и Inbox программно — или подключите ИИ (Claude и др.) через MCP, чтобы он делал это за вас.

1. Авторизация и соглашения

Все запросы — с заголовком Authorization: Bearer bs_live_…. Ключ создаётся в кабинете: Настройки → API → Создать ключ (показывается один раз). У ключа есть область (весь воркспейс / организация / проект) и роль (admin / editor / operator) — по умолчанию весь воркспейс + admin; для интеграций давайте самую узкую область и роль (наименьшие привилегии). Биллинг доступен только ключу на весь воркспейс с ролью admin.

Базовый адрес API: https://ultrabot.work/api

curl https://ultrabot.work/api/bots \
  -H "Authorization: Bearer bs_live_ВАШ_КЛЮЧ"

Ключи через API

Ключами можно управлять и программно: GET /api/keys — список {id, name, prefix, created_at, revoked}; POST /api/keys {name} → {key, prefix, name} (полный ключ bs_live_… возвращается один раз — сохраните сразу); POST /api/keys/revoke {id} — отозвать. Один ключ = один воркспейс.

Форматы и ошибки

Тело запросов и ответов — JSON (content-type: application/json). Успех — код 2xx и JSON. Ошибка возвращается HTTP-кодом, а тело — обычный текст сообщения (не JSON): ориентируйтесь на статус-код, текст показывайте как есть.

Код	Значение
`400`	Неверный запрос (тело/параметры)
`401`	Нет или просрочена авторизация
`402`	Достигнут лимит тарифа — нужен апгрейд
`403`	Недостаточно прав (роль)
`404`	Не найдено
`429`	Превышен лимит частоты запросов
`5xx`	Ошибка сервера

Лимиты частоты

По паре IP+путь, окно 60 секунд: register/forgot — 5; login/reset-confirm — 20; billing/subscribe — 10; bots/import — 10; templates/clone — 20; сообщения виджета — 60. Остальные ручки — без жёсткого лимита. При превышении — 429.

ID и идемпотентность

ID бота — вида bot_…; ID диалога (sid) — это chat id строкой. PUT /api/bots/{id}/graph — полная замена черновика (не патч). POST /api/bots/{id}/publish создаёт новую версию-снапшот (повторный publish = новая версия; откат — POST /api/bots/{id}/rollback/{version}).

2. Быстрый старт: создать и опубликовать бота

# 1) создать бота (вернёт id)
curl -X POST https://ultrabot.work/api/bots \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"name":"Мой бот"}'

# 2) задать сценарий (граф)
curl -X PUT https://ultrabot.work/api/bots/BOT_ID/graph \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"states":[...],"transitions":[...]}'

# 3) подключить Telegram и опубликовать
curl -X PUT https://ultrabot.work/api/bots/BOT_ID/telegram \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" -d '{"token":"123:ABC"}'
curl -X POST https://ultrabot.work/api/bots/BOT_ID/publish -H "Authorization: Bearer $KEY"

3. Полный справочник эндпоинтов

Базовый адрес: https://ultrabot.work/api. Все запросы — с Authorization: Bearer bs_live_…. Ключ действует в своей области и роли (по умолчанию — весь воркспейс, admin; тогда доступны все ручки ниже, кроме платформенной админки супер-админа). {id} — ID бота, {sid} — ID диалога (chat id).

Боты и граф

Метод и путь	Описание
GET /api/bots	Список активных ботов
POST /api/bots	Создать бота (черновик) `{name}` → `{id}`
GET /api/bots/{id}	Бот + граф (states, transitions)
PUT /api/bots/{id}	Переименовать бота `{name}`
PUT /api/bots/{id}/graph	Заменить граф `{states, transitions}`
POST /api/bots/{id}/publish	Опубликовать (снапшот графа → боевой)
GET /api/bots/{id}/validate	Проверка графа: ошибки/предупреждения
POST /api/bots/{id}/simulate	Тест-прогон `{text}` \| `{button}` \| `{reset:true}`
GET /api/bots/{id}/versions	История публикаций
POST /api/bots/{id}/rollback/{version}	Откатить публикацию к версии
GET /api/bots/{id}/export	Экспорт бота в JSON
POST /api/bots/import	Импорт бота из JSON
GET /api/templates · POST /api/templates/{tid}/clone	Галерея готовых сценариев и клонирование
DELETE /api/bots/{id}	Удалить в корзину (мягко: бот перестаёт отвечать, освобождает лимит)
GET /api/bots/archived	Корзина: удалённые боты
POST /api/bots/{id}/restore	Восстановить из корзины (в черновики)
DELETE /api/bots/{id}/purge	Стереть навсегда (только из корзины) — необратимо

Виджет на сайт

Плавающая кнопка чата на любом сайте — одной строкой (async, не тормозит страницу; на мобиле — на весь экран):

<script src="https://ultrabot.work/widget.js" data-bot="BOT_ID" async></script>

Вид (цвет, позиция, круглая кнопка/боковой таб, тема, приветствие-бабл, аватар, брендинг) настраивается в кабинете: бот → Чат на сайт. Публичный конфиг — GET /api/widget/{id}/config; сохранить — PUT /api/bots/{id}/widget (editor+). Альтернатива — встраивание через <iframe src="https://ultrabot.work/widget/BOT_ID">.

Каналы

Метод и путь	Описание
GET/PUT /api/bots/{id}/telegram	Подключить Telegram `{token}`
GET/PUT /api/bots/{id}/viber	Подключить Viber `{token}`
GET/PUT /api/bots/{id}/channel/{name}	Внешний канал: vk, ok, max, whatsapp, instagram, messenger, avito
GET/PUT /api/bots/{id}/commands	Меню команд Telegram `{list}`
GET/PUT /api/bots/{id}/comments-reply	Автоответ на комментарии → в ЛС
GET/PUT /api/bots/{id}/webhook-out	Исходящие вебхуки на события бота

Маркетинг

Метод и путь	Описание
GET/POST /api/bots/{id}/broadcasts	Рассылки (с сегментами/расписанием)
GET /api/bots/{id}/segment-count?tag=	Размер сегмента по метке
GET/POST /api/bots/{id}/sequences	Drip-цепочки
DELETE /api/bots/{id}/sequences/{sid}	Удалить цепочку
POST /api/bots/{id}/sequences/{sid}/enroll-all	Записать всех контактов в цепочку

Контакты и CRM

Метод и путь	Описание
GET /api/bots/{id}/contacts?tag=&q=	Подписчики (фильтр по метке/поиск)
POST /api/bots/{id}/contacts/tag	Метка подписчику `{cid, tag, action}`
POST /api/bots/{id}/contacts/bulk-tag	Массовая простановка метки
GET /api/bots/{id}/contacts/export	Экспорт подписчиков в CSV
GET/POST /api/bots/{id}/deals · DELETE …/deals/{did}	Мини-CRM: сделки
GET/POST /api/bots/{id}/products · DELETE …/products/{pid}	Каталог товаров

AI и база знаний

Метод и путь	Описание
GET/PUT /api/bots/{id}/ai	AI-провайдер бота `{provider, api_key, model}`
GET/POST /api/bots/{id}/knowledge · DELETE …/knowledge/{doc_id}	База знаний (RAG) `{title, text}`
POST /api/bots/{id}/knowledge/reindex	Векторный реиндекс базы знаний
GET/PUT /api/bots/{id}/provider/{name}	Интеграции: bitrix, amocrm, sheets, yookassa, sms

Аналитика

Метод и путь	Описание
GET /api/bots/{id}/stats	Диалоги, сообщения, конверсия
GET /api/bots/{id}/radar	Источники трафика (по `?start=`)

Inbox (диалоги и оператор)

Метод и путь	Описание
GET /api/inbox?filter=	Диалоги: waiting \| active \| mine \| closed
GET /api/inbox/counts	Счётчики по вкладкам
GET /api/inbox/{id}/{sid}/messages	Сообщения диалога
POST /api/inbox/{id}/{sid}/reply	Ответ оператора `{text}`
POST /api/inbox/{id}/{sid}/assign	Назначить диалог на себя/оператора
POST /api/inbox/{id}/{sid}/status	Статус диалога `{status}` (в т.ч. closed)
POST /api/inbox/{id}/{sid}/note	Внутренняя заметка оператора

Организации, проекты и доступы

Иерархия: воркспейс → организация → проект → бот. Тариф и лимиты — на воркспейс (общий пул). У воркспейса есть дефолтные организация и проект, поэтому соло-пользователь их не замечает. Роли (наследуются каскадом сверху вниз, действуют на своём уровне и ниже): admin — полный доступ, editor — правит ботов, operator — только отвечает в диалогах, billing — только оплата (только на уровне воркспейса). Доступ выдаётся на любом уровне; в проект можно приглашать внешних коллабораторов.

Метод и путь	Описание
GET /api/orgs	Организации воркспейса с их проектами
POST /api/orgs	Создать организацию `{name}`
PUT /api/orgs/{id} · DELETE /api/orgs/{id}	Переименовать / удалить организацию (пустую)
POST /api/projects	Создать проект `{org_id, name}`
PUT /api/projects/{id} · DELETE /api/projects/{id}	Переименовать / удалить проект (пустой)
PUT /api/bots/{id}/move	Перенести бота в проект `{project_id}`
GET /api/access?scope_type=tenant\|org\|project&scope_id=	Кто имеет доступ к уровню
POST /api/access	Выдать доступ `{scope_type, scope_id, email, role}` (новому email — аккаунт + письмо-приглашение)
DELETE /api/access	Снять доступ `{scope_type, scope_id, email}`

Воркспейс: тариф, платильщик, ключи

Метод и путь	Описание
GET /api/billing	Тариф, лимиты, использование, платильщик (`payer_email`), способы оплаты (`psps`)
GET /api/billing/payments	История платежей
POST /api/billing/payer	Назначить платильщика воркспейса `{email}`
GET /api/keys	API-ключи воркспейса

Тариф, лимиты и платежи — на воркспейс (как и API-ключ). Оплачивает платильщик (по умолчанию — создатель, переназначается tenant-админом); цены мультивалютные (RUB/KZT/USD/EUR — сумма берётся по выбранному способу оплаты). Участники команды управляются через /api/access (scope_type=tenant), роли admin/editor/operator/billing. Один ключ = один воркспейс.

4. Схема графа бота

Сценарий — это states (узлы) и transitions (переходы). Минимальный бот:

{
  "states": [
    {"id":"start","type":"start","label":"Старт","config":{},"position":{"x":80,"y":80}},
    {"id":"hello","type":"message","label":"Привет","config":{"text":"Здравствуйте! Чем помочь?"},"position":{"x":80,"y":220}}
  ],
  "transitions": [
    {"id":"t1","from":"start","to":"hello","type":"goto","condition":null}
  ]
}

Основные типы узлов (type) и их config:

type	config	Назначение
`start`	—	Точка входа
`trigger`	`{event, keywords, match}`	Запуск ветки по слову (keyword) или на нового подписчика (subscribe)
`message`	`{text, media_url?, buttons?}`	Отправить сообщение (кнопки — через переходы `on_button`)
`input`	`{var}`	Ждать ответ, сохранить в переменную
`condition`	`{var, op, value}`	Ветвление (переходы `on_condition` с `result:true/false`)
`set_var`	`{var, value}`	Записать переменную
`api_call`	`{url, method, body, save_to}`	HTTP-запрос во внешний сервис
`ai`	`{prompt, use_kb, save_to, task}`	AI-ответ по базе знаний
`tag`	`{action, tag}`	Навесить/снять метку подписчику
`set_field`	`{field, value}`	Записать кастом-поле подписчика
`payment`	`{provider, amount, ...}`	Оплата: YooKassa (ссылка) или Telegram Stars (в чате)
`bitrix` / `amocrm` / `sheets`	`{fields}` / `{columns}`	Отправить данные в Bitrix24 / amoCRM / Google Таблицы
`handoff`	—	Передать оператору (в Inbox)

Совет: получите граф готового бота через GET /api/bots/{id} — это лучший образец формата для правки.

5. Исходящие вебхуки (события бота)

Платформа может уведомлять ваш сервер о событиях бота. Настройка:

curl -X PUT https://ultrabot.work/api/bots/BOT_ID/webhook-out \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"url":"https://your.app/hook","events":{"subscribe":true,"handoff":true,"deal":true,"payment":true}}'

Каждое событие включается флагом true/false. При событии платформа делает POST на ваш url (таймаут 10 с, редиректы не следуются, повторных попыток нет — держите обработчик быстрым и идемпотентным). Тело всегда одной формы {event, bot_id, data}:

{"event":"subscribe","bot_id":"bot_ab12…","data":{"chat_id":123,"name":"Иван","channel":"telegram"}}

event	Когда	data
`subscribe`	Новый подписчик	`{"chat_id":123,"name":"Иван","channel":"telegram"}`
`handoff`	Диалог передан оператору (узел handoff)	chat_id числом, напр. `123`
`deal`	Создана сделка (узел deal)	`{"title":"Заказ","amount":1990,"stage":"new"}`
`payment`	Успешная оплата в боте (Telegram-платёж)	`{"chat_id":123,"payload":"payload инвойса"}`

6. Примеры интеграций

Создать рассылку (сегмент по метке, канал push или email):

curl -X POST https://ultrabot.work/api/bots/BOT_ID/broadcasts \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"text":"Акция!","filter_tag":"vip","channel":"push"}'

Опционально: buttons, subject (для email), scheduled_at (ISO-время), repeat_days, filter_var/filter_value, delay_seconds.

Навесить метку контакту (action: add | remove):

curl -X POST https://ultrabot.work/api/bots/BOT_ID/contacts/tag \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"cid":"CHAT_ID","tag":"vip","action":"add"}'

Inbox: список ожидающих диалогов и ответ оператора:

curl "https://ultrabot.work/api/inbox?filter=waiting" -H "Authorization: Bearer $KEY"
curl -X POST https://ultrabot.work/api/inbox/BOT_ID/SID/reply \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"text":"Здравствуйте!"}'

Тариф и лимиты воркспейса:

curl https://ultrabot.work/api/billing -H "Authorization: Bearer $KEY"
# → {"plan":"pro","limits":{"max_bots":10,"max_broadcasts_month":100,"max_contacts":10000},
#     "usage":{...},"payer_email":"...","psps":["robokassa"]}

7. Подключение ИИ (MCP)

Через Model Context Protocol ИИ получает инструменты, которые дёргают этот API с вашим ключом — и может сам создавать/настраивать ботов, вести Inbox и т.д. Два способа:

Вариант А — удалённый MCP (без установки)

Просто добавьте сервер по URL. Для Claude Desktop / клиентов с remote-MCP:

{
  "mcpServers": {
    "ultrabot": {
      "url": "https://ultrabot.work/mcp",
      "headers": { "Authorization": "Bearer bs_live_ВАШ_КЛЮЧ" }
    }
  }
}

Вариант Б — локальный сервер (stdio)

Для Claude Desktop / Claude Code, где нужен локальный процесс:

{
  "mcpServers": {
    "ultrabot": {
      "command": "npx",
      "args": ["-y", "@ultrabot/mcp"],
      "env": {
        "ULTRABOT_API_KEY": "bs_live_ВАШ_КЛЮЧ",
        "ULTRABOT_BASE_URL": "https://ultrabot.work"
      }
    }
  }
}

Доступные инструменты: list_bots, create_bot, get_bot, rename_bot, delete_bot, list_archived_bots, restore_bot, purge_bot, update_graph, publish_bot, bot_overview, bot_stats, connect_telegram, set_channel, create_broadcast, list_dialogs, dialog_messages, reply_dialog, set_ai, add_knowledge, list_contacts, tag_contact, set_commands, billing_status.

Пример запроса к пользователю: «Создай бота-автоответчик для записи в барбершоп, подключи мой Telegram и опубликуй» — ИИ вызовет create_bot → update_graph → connect_telegram → publish_bot.

Получите ключ и начните

Ключи — в кабинете, раздел «Настройки → API».

Открыть кабинет