Ассистенты

Ассистент

Ассистент — это бот со всеми настройками: модели, первые экраны, пейволл, языки, домен, Telegram. Настройки хранятся в самом ассистенте, агенты, первые экраны, версии и обращения — отдельными записями, привязанными к нему.

Объект ассистента в ответах GET /assistants и GET /assistants/{assistantId} содержит все его поля. В JSON он по историческим причинам лежит под ключом project (список — projects). Менять поля нужно не здесь, а методами разделов (PUT /assistants/{assistantId}/bot, /paywall и т. д.) — в таблице свойств ниже указано, где каждое поле меняется.

Методы

Список ассистентов

Возвращает все ассистенты, доступные ключу: свои и расшаренные вам. Новые сверху (по убыванию id). Пагинации нет.

GET /assistants

Параметров нет.

curl -s "$BASE/assistants" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "projects": [
    {
      "id": 53,
      "name": "bota.chat",
      "url": null,
      "title": null,
      "user_id": 1,
      "is_system": 0,
      "created_at": "2026-04-30T10:59:07.000000Z",
      "updated_at": "2026-09-25T18:41:46.000000Z",
      "frame_slug": "x8OA7Azs4hBy",
      "tg_bot_username": "bota_chat_bot",
      "custom_domain": "bota.chat",
      "ai_model": "default-model",
      "default_model": "~google/gemini-flash-latest",
      "enabled_models": ["anthropic/claude-opus-5", "…"],
      "currency": "RUB",
      "billing_mode": "tokens",
      "locales": ["ru", "en", "…"],
      "default_locale": "ru",
      "bot_name": "Новый ассистент",
      "bot_avatar": "default",
      "shared_user_ids": [533, 601],
      "capability_images": true,
      "tickets_enabled": true,
      "tg_bot_token_set": true,
      …
    }
  ]
}

HTTP	Когда
401	Ключ не передан или неверный

Получить ассистента

Один ассистент по id — тот же объект, что в списке.

GET /assistants/{assistantId}

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути. Только число: нечисловое значение — 404

curl -s "$BASE/assistants/$ASSISTANT" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "project": {
    "id": 53,
    "name": "bota.chat",
    "frame_slug": "x8OA7Azs4hBy",
    …
  }
}

HTTP	Когда
404	{"success": false, "error": "Project not found or access denied"} — ассистент чужой или не существует

Создать ассистента

Создаёт нового ассистента, владелец — пользователь ключа. Сервер сам выпускает ключ ассистента site_… (получить его — GET /assistants/{assistantId}/api-key), адрес страницы чата frame_slug, ставит модели по умолчанию, включает обращения в поддержку и подставляет аватар бота из профиля пользователя.

POST /assistants

Параметр	Тип	Обяз.	Описание
name	string	нет	Внутреннее название в дашборде, до 255 символов. Посетители его не видят. Не передано — ставится «Новый ассистент #K42» (буква и две цифры)
url	string	нет	Адрес сайта ассистента, валидный URL до 255 символов
interface_locale	string	нет	Язык кнопок и подписей интерфейса чата: ru, en или auto. auto и отсутствие поля — язык определяется автоматически

Публичное имя бота (bot_name) при создании пустое, его задают через PUT /assistants/{assistantId}/bot.

curl -s -X POST "$BASE/assistants" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Юрист — тест", "url": "https://example.com", "interface_locale": "ru"}'

Ответ 201 — объект нового ассистента. Это единственный ответ с объектом ассистента, где есть его ключ api_key (site_…): сохраните его сразу, потом его отдаёт только GET /assistants/{assistantId}/api-key:

{
  "success": true,
  "project": {
    "id": 512,
    "name": "Юрист — тест",
    "url": "https://example.com",
    "user_id": 1,
    "interface_locale": "ru",
    "frame_slug": "Ab3dE5fG7hJ9",
    "ai_model": "default-model",
    "default_model": "~google/gemini-flash-latest",
    "bot_avatar": "default",
    "tickets_enabled": true,
    "enabled_models": ["…"],
    "created_at": "2026-09-25T20:00:00.000000Z",
    "updated_at": "2026-09-25T20:00:00.000000Z",
    "tg_bot_token_set": false,
    "api_key": "site_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

В ответе на создание только заданные поля; полный объект со значениями по умолчанию вернёт GET /assistants/{assistantId}.

HTTP	Когда
422	{"success": false, "errors": {"url": ["The url field must be a valid URL."], "interface_locale": ["The selected interface locale is invalid."]}}

Удалить ассистента

Удаляет ассистента без возможности восстановления. Удалить может только владелец: для расшаренного пользователя чужой ассистент здесь не существует.

DELETE /assistants/{assistantId}

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути

curl -s -X DELETE "$BASE/assistants/$ASSISTANT" \
  -H "Authorization: Bearer $KEY"

{ "success": true, "message": "Project deleted" }

HTTP	Когда
404	Ассистент не существует, чужой или вы не владелец, а расшаренный пользователь

clear

Удаление необратимо

Ассистент удаляется из базы сразу, корзины нет. Вместе с ним удаляются агенты, первые экраны, чаты и сообщения, кредиты, подписки и платежи посетителей. Подтверждения сервер не спрашивает — проверяйте id перед запросом.

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

Ключ site_… нужен для методов чатов. Это единственный способ его получить: в объекте ассистента ключа нет.

GET /assistants/{assistantId}/api-key

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути

curl -s "$BASE/assistants/$ASSISTANT/api-key" \
  -H "Authorization: Bearer $KEY"

{ "success": true, "api_key": "site_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

HTTP	Когда
404	Ассистент чужой или не существует

Перевыпустить ключ ассистента

Выдаёт новый ключ site_…. Старый перестаёт работать сразу: интеграции, которые создают чаты и шлют сообщения по нему, начнут получать 401 {"success": false, "error": "Invalid API key", …}. Личный ключ user_… это не затрагивает. Доступно владельцу и расшаренным пользователям.

POST /assistants/{assistantId}/api-key/regenerate

Параметр	Тип	Обяз.	Описание
assistantId	integer	да	id ассистента, в пути

curl -s -X POST "$BASE/assistants/$ASSISTANT/api-key/regenerate" \
  -H "Authorization: Bearer $KEY"

{ "success": true, "api_key": "site_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "message": "API key regenerated" }

HTTP	Когда
404	Ассистент чужой или не существует

info

Секретов в объекте ассистента нет

Объект ассистента не содержит его ключ, токен Telegram-бота и секрет вебхука Telegram. Ключ ассистента отдаёт GET /assistants/{assistantId}/api-key и один раз ответ POST /assistants, про токен бота говорит флаг tg_bot_token_set.

Свойства ассистента

Все поля объекта. Колонка «Описание» указывает умолчание для нового ассистента и раздел, где поле меняется. Поля с типом object или array описаны подробно на страницах разделов.

Служебные

Свойство	Тип	Описание
id	integer	id ассистента
user_id	integer	id владельца
shared_user_ids	array или null	id пользователей, которым открыт доступ. См. Доступ
name	string	Внутреннее название в дашборде, до 255 символов. Меняется в настройках бота
url	string или null	Адрес сайта, задаётся при создании
title	string или null	Устаревшее название, используется, только если name пустой
is_system	integer	1 — служебный ассистент площадки, исключён из метрик. У ассистентов владельцев 0
frame_slug	string	12 символов, адрес страницы чата https://framesuite.app/f/{frame_slug}
created_at, updated_at	string	ISO 8601, UTC
parsing_status, parsing_progress, parsing_total, parsing_error, last_parsed_at	string, integer, integer, string, string	Состояние разбора сайта для базы знаний: idle в покое

Бот и шапка чата

Меняются через Настройки бота и шапка.

Свойство	Тип	Описание
bot_name	string или null	Публичное имя ассистента, до 100 символов. При создании пустое
bot_avatar	string	Имя файла аватара без пути и расширения или default
avatar_type	string	persona (сгенерированный персонаж, по умолчанию), custom (загруженная картинка), none
persona_variant	string	Вариант персонажа, по умолчанию obsidian
bot_gender	string или null	male, female
bot_locales	object или null	Языковые версии: {"en": {"bot_name", "bot_avatar", "bot_gender", "header_logo", "header_logo_dark", "header_icon", "header_icon_dark", "sidebar_pages"}}. Пишется полем bot_locales в PUT /bot, слиянием по языкам и полям
thinking_text	string или null	Подпись, пока ассистент думает, до 100 символов
response_style	string	text (по умолчанию) или messenger
interface_locale	string или null	Язык интерфейса чата: ru, en; null — автоматически
primary_color	string или null	Акцентный цвет #RRGGBB; null — цвета темы
header_note	string или null	Дисклеймер по центру шапки на первом экране
header_logo, header_logo_dark, header_icon, header_icon_dark	string или null	Логотип и знак в шапке для светлой и тёмной темы, URL
documents_empty_icon	string или null	Картинка пустой панели «Документы», URL
system_prompt	string или null	Системный промпт ассистента
show_tooltip, tooltip_text	boolean, string или null	Подсказка у кнопки виджета
welcome_avatar	string или null	Картинка над заголовком первого экрана, URL

Модели

Меняются через Модели.

Свойство	Тип	Описание
ai_model	string	Стартовая модель чата. По умолчанию default-model — «Default» в интерфейсе
default_model	string	Модель, скрытая за «Default». По умолчанию ~google/gemini-flash-latest
enabled_models	array	id моделей, доступных в переключателе
free_model	string или null	Модель для неоплативших посетителей
image_model	string или null	Модель картинок по умолчанию
enabled_image_models	array или null	Доступные модели картинок
video_model	string или null	Модель видео
credit_multiplier	number	Маржа: во сколько раз списание кредитов больше себестоимости, от 1 до 10

Возможности, сайдбар, задержка

Меняются через Возможности, сайдбар и задержка.

Свойство	Тип	Описание
capability_images, capability_video, capability_diagrams, capability_plots, capability_files_output, capability_search, capability_voice_input, capability_voice_mode, capability_model_selector, capability_memory	boolean	Включённые возможности чата
capability_agent	boolean	Авто-режим: ассистент сам переключается на подходящего агента
search_max_results	integer	Сколько результатов поиска брать, 1–20
default_chat_mode	string	Режим чата по умолчанию: text, image, diagram, plot
sidebar_pages	array	Пункты боковой панели, например ["agents", "tickets"]
sidebar_open_default	boolean	Панель открыта при входе
sidebar_default_tab	string	Вкладка по умолчанию: chats или documents
tickets_enabled	boolean	Обращения в поддержку включены. У нового ассистента true
delay_enabled, delay_min_sec, delay_max_sec, delay_skip_paid, delay_skip_auth	boolean, number, number, boolean, boolean	Пауза перед ответом: вкл, от и до секунд, пропуск для оплативших и вошедших
delay_text, delay_text_locales, delay_note_text, delay_note_text_locales	string, object	Тексты во время паузы, общие и по языкам

Агенты и варианты ответа

Общие настройки агентов ассистента, меняются через Настройки бота. Сами агенты — Агенты.

Свойство	Тип	Описание
agent_system_prompt	string или null	Промпт авто-режима
agent_reasoning	boolean	Рассуждение модели в авто-режиме
agent_post	boolean	Варианты ответа после сообщения ассистента
agent_post_system_prompt	string или null	Свой промпт генерации вариантов ответа
agent_post_reasoning, agent_post_first_only, agent_post_use_selected_model	boolean	Рассуждение, только после первого ответа, генерировать выбранной моделью
sticky_first_suggestions	boolean	Первые подсказки остаются на экране
commands_cache_enabled	boolean	Кэш ответов на кнопки агентов, по умолчанию true

Первые экраны, онбординг, шаблоны

Меняются через Первые экраны, Онбординг, Шаблоны и подвал.

Свойство	Тип	Описание
welcome_message, welcome_subtitle	string или null	Заголовок и подзаголовок первого экрана
input_placeholder	string или null	Подсказка в поле ввода
quick_actions	array	Старые быстрые кнопки
welcome_sections	array	Секции карточек агентов: {"category", "title", "limit"}
welcome_locales	object или null	Тексты и секции первого экрана по языкам
welcome_mode	string	Поведение первого экрана, по умолчанию new_chat
welcome_collapsed_limit	integer	Сколько карточек видно до «Показать ещё», по умолчанию 999
intro_slides, intro_slides_locales	array, object	Слайды онбординга, общие и по языкам
templates	object	Подвал, адреса пунктов боковой панели (sidebar_links), тексты каталога (agents_catalog), тег каталога и категория шаблонов (sidebar.agents_tag, sidebar.templates_category)

Пейволл и оплата

Меняются через Пейволл и тарифы.

Свойство	Тип	Описание
billing_mode	string	tokens (кредиты) или subscription
currency	string	RUB или USD
default_credits	integer	Бесплатные кредиты новому посетителю
paywall_trigger	string	Когда показывать пейволл: never, credits, messages
messages_limit	integer	Бесплатных сообщений при paywall_trigger = messages, 1–1000
paywall_limit_action	string	Что делать на лимите: paywall или cliffhanger
paywall_cliffhanger_instruction	string или null	Инструкция модели для обрыва на интересном месте
paywall_auto_google_login	boolean	Сразу предлагать вход через Google
paid_features, login_required	object	Какие возможности только за оплату и только после входа: files, media, voice, memory, models, search, agent. Меняются в /features, слиянием по ключам
pricing_plans	array	Тарифы
paywall_texts, paywall_features	object, array	Тексты и преимущества на пейволле
paywall_locales	object или null	Тарифы и тексты по языкам
custom_paywall_enabled, paywall_default_enabled, paywall_default_types	boolean, boolean, array	Свой HTML-пейволл и стандартный — см. Свои HTML-шаблоны
auth_panel_enabled, auth_panel_title, auth_panel_subtitle, auth_features_title, auth_features, auth_reviews, auth_locales	boolean, string, array, object	Боковая панель окна входа: заголовки, преимущества, отзывы
payment_description	string или null	Назначение платежа
payment_account_rub_id, payment_account_usd_id	integer или null	Кассы для рублей и валюты
paddle_product_id	string или null	Продукт в Paddle

Языки

Меняются через Языки и переводы.

Свойство	Тип	Описание
locales	array	Языки ассистента
default_locale	string	Язык по умолчанию

Домен и Telegram

Меняются через Домены, Telegram, встраивание.

Свойство	Тип	Описание
custom_domain	string или null	Основной свой домен
tg_bot_username, tg_bot_app_name	string или null	Имя Telegram-бота и Mini App
tg_bot_token_set	boolean	Токен бота задан. Сам токен не отдаётся
tg_short_description, tg_description, tg_start_message	string или null	Тексты бота в Telegram

Поддержка и партнёрка

Меняются через Поддержка и обращения и Партнёрская программа.

Свойство	Тип	Описание
support_name, support_avatar	string или null	Имя и аватар поддержки
support_locales	array или object	Пустое состояние окна поддержки по языкам: empty_title, empty_description, empty_cta, empty_image. Сливается по языкам и полям
partner_enabled	boolean	Партнёрская программа включена
partner_percent	string	Процент партнёра, строка с двумя знаками: "50.00"

Дальше

• Настройки бота и шапка
• Доступ
• Чаты по ключу ассистента