Возможности чата, боковая панель и задержка в API bota.chat

Возможности чата и боковая панель пишутся одним методом /features, адреса пунктов панели — в контейнере /templates, задержка перед ответом — методом /delay. Все записи частичные: меняется только то, что пришло в теле.

BASE=https://framesuite.app/api/v1
KEY=user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ASSISTANT=53

Возможности

Получить возможности

GET /assistants/{assistantId}/features

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь. Id ассистента.

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

{
  "success": true,
  "capability_images": true,
  "capability_diagrams": false,
  "capability_plots": false,
  "capability_files_output": true,
  "capability_search": true,
  "capability_voice_input": true,
  "capability_voice_mode": true,
  "capability_model_selector": true,
  "capability_memory": false,
  "capability_video": false,
  "capability_agent": true,
  "tickets_enabled": true,
  "search_max_results": 6,
  "default_chat_mode": "text",
  "paid_features": {
    "files": false,
    "media": true,
    "voice": false,
    "memory": false,
    "models": true,
    "search": false
  },
  "login_required": {
    "files": false,
    "media": false,
    "voice": false,
    "memory": false,
    "models": false,
    "search": false
  },
  "sidebar_pages": ["agents"],
  "sidebar_open_default": false,
  "sidebar_default_tab": "chats",
  "sidebar_templates_category": null
}

HTTP	Когда
200	Настройки отданы.
404	Ассистента нет или к нему нет доступа: `{"success":false,"error":"Project not found or access denied"}`.

Свойства возможностей

Свойство	Тип	Описание
`capability_images`	boolean	Генерация картинок. Модели — в /models.
`capability_diagrams`	boolean	Генерация диаграмм.
`capability_plots`	boolean	Графики.
`capability_files_output`	boolean	Ассистент выдаёт файлы и документы. Без неё нет страницы «Шаблоны документов».
`capability_search`	boolean	Веб-поиск.
`search_max_results`	integer, 1–20	Сколько результатов поиска получает модель. По умолчанию 6, `null` возвращает 6.
`capability_voice_input`	boolean	Микрофон в поле ввода. По умолчанию `true`.
`capability_voice_mode`	boolean	Полноэкранный голосовой режим, кнопка в шапке чата.
`capability_model_selector`	boolean	Выбор модели в чате. По умолчанию `true`.
`capability_memory`	boolean	Память между диалогами. Работает только вместе с `capability_agent`.
`capability_video`	boolean	Генерация видео. Модель — `video_model` в /models.
`capability_agent`	boolean	Агентский режим: ассистент сам вызывает инструменты (поиск, память, переключение на подходящего агента).
`default_chat_mode`	string	Режим, в котором открывается чат: `text` (по умолчанию), `image`, `diagram`, `plot`. `null` ничего не меняет.
`tickets_enabled`	boolean	Обращения в поддержку у ассистента. Включает значок поддержки в шапке чата, действие поддержки в подвале приветствия и страницу обращений по ссылке `?lib=tickets`. Пункт в боковой панели — отдельно, через `sidebar_pages`. См. Поддержка и обращения.
`paid_features`	object	Какие функции только для платящих. Ключи ниже.
`login_required`	object	Какие функции только после входа. Те же ключи.

Ключи paid_features и login_required, значения — boolean:

Ключ	Что закрывает
`media`	Картинки, диаграммы, графики.
`voice`	Голосовой ввод и голосовой режим.
`models`	Выбор модели.
`search`	Веб-поиск.
`files`	Вложения.
`memory`	Память.
`agent`	Агентский режим. Без оплаты или входа чат тихо работает в обычном режиме, без пейволла.

Остальные функции при срабатывании замка открывают пейволл или окно входа. «Платящий» — у кого активная подписка или хотя бы одна оплаченная покупка; стартовые бесплатные кредиты покупкой не считаются. Владелец ассистента не ограничивается.

Изменить возможности

PUT /assistants/{assistantId}/features

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь. Id ассистента.
`strict`	boolean	нет	Тело или строка запроса. `true` — незнакомое поле даёт 422, ничего не пишется.
остальные	—	нет	Тело, JSON. Свойства возможностей и боковой панели.

paid_features и login_required сливаются с сохранёнными по ключам: {"paid_features": {"voice": false}} меняет только voice, остальные ключи остаются как были. Незнакомые ключи отбрасываются. До 26.09.2026 карта заменялась целиком, и неприсланный ключ пропадал.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/features" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"search_max_results":6}'

{
  "success": true,
  "applied": ["search_max_results"],
  "ignored": []
}

HTTP	Когда
200	Записано. `applied` — записанные поля, `ignored` — незнакомые.
404	Ассистента нет или к нему нет доступа.
422	Ошибка валидации: `{"success":false,"errors":{"default_chat_mode":["The selected default chat mode is invalid."]}}`.
422	`strict=true` и незнакомое поле: `{"success":false,"error":"unknown_fields","message":"Unknown fields: …","ignored":[…]}`.

Открытая вкладка настроек перезапишет изменения

Страница «Возможности» в настройках ассистента сохраняет все свои поля разом. Если вкладка была открыта до записи через API, её «Сохранить» вернёт старые значения. После записи через API перезагрузите вкладку.

Боковая панель чата

В боковой панели чата, кроме списка диалогов, есть пункты-страницы. Каждая такая страница открывается внутри чата и живёт в адресе параметром ?lib=<id>.

Id страницы	Пункт	Условия
`agents`	«Помощники» — каталог агентов	Пункт — по списку `sidebar_pages`. Сама страница по ссылке `?lib=agents` открывается у любого ассистента. Подпись, тексты каталога и тег отбора агентов (`templates.sidebar.agents_tag`) — в Каталог «Помощники».
`samples`	«Шаблоны документов»	Нужна `capability_files_output`. Без страницы в `sidebar_pages` недоступна и ссылка `?lib=samples`.
`tickets`	«Поддержка»	Нужен `tickets_enabled`. Пункт — по списку, а значок в шапке и ссылка `?lib=tickets` работают при `tickets_enabled` и без него в списке.

Отдельно от страниц в панели есть пункт «Мои документы» (витрина файлов человека). Он не входит в sidebar_pages, но может вести на свой адрес, см. ниже.

Свойства боковой панели

Пишутся в PUT /features, читаются в GET /features.

Свойство	Тип	Описание
`sidebar_pages`	array строк, до 64 символов каждая	Пункты-страницы в панели. Порядок задаёт сама панель (`samples`, `agents`, `tickets`), порядок в массиве не важен. Заменяется целиком, пустые значения и повторы выбрасываются. `[]` — пунктов нет. По умолчанию `[]`.
`sidebar_open_default`	boolean	Панель раскрыта при первом заходе. Если человек уже сам сворачивал или разворачивал панель, побеждает его выбор. По умолчанию `false`.
`sidebar_default_tab`	string	С какой вкладки открывается панель: `chats` (по умолчанию) или `documents`. Действует при каждой загрузке. `null` или пустое значение ничего не меняют.
`sidebar_templates_category`	string или null, до 191	Категория агентов для вкладки «Готовые» страницы «Шаблоны документов», если на приветственном экране нет секции `templates`. Секция на экране главнее. Пустая строка или `null` снимают настройку. Хранится в `templates.sidebar.templates_category`, то же поле пишет `PUT /templates` с `{"sidebar": {"templates_category": "…"}}`.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/features" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"sidebar_pages":["agents","tickets"],"sidebar_open_default":true}'

Чтобы убрать один пункт, пришлите список без него. У каждого языка может быть свой список пунктов (например, без «Шаблонов документов» у англоязычных посетителей) — поле bot_locales.<язык>.sidebar_pages в PUT /bot, см. Настройки бота. Список языка действует только на этом языке и заменяет sidebar_pages целиком, [] — пунктов нет.

Адреса пунктов боковой панели

Пункт панели может вести не на страницу внутри чата, а на страницу сайта. Например, у bota.chat пункт «Помощники» ведёт на /base/, где каталог собран отдельной страницей сайта. Адреса хранятся в контейнере шаблонов ассистента, ключ sidebar_links, и пишутся методом PUT /assistants/{assistantId}/templates — подробности метода на странице Шаблоны и подвал.

Свойство	Тип	Описание
`sidebar_links`	object или null, до 20 ключей	Карта «пункт → адрес». Ключи: `agents`, `samples`, `tickets`, `documents` («Мои документы»). Значение — полный адрес `http(s)://…` или путь от корня сайта до 1024 символов.

Как сервер приводит адрес:

Прислали	Сохранится
`https://example.com/catalog`	как есть
`base`	`/base/`
`/base/canva`	`/base/canva/`
`/base?tab=new`	`/base/?tab=new`
пусто, с пробелами внутри, `//host`, `javascript:…`	пункт без адреса

Путь достраивается до полного адреса в браузере: если чат встроен в сайт или открыт на своём домене ассистента — от этого домена, если на служебном адресе framesuite.app/f/<slug> — от основного домена ассистента. Если домена нет, пункт открывается внутри чата. Пункт с адресом — обычная ссылка, а не страница внутри чата. Показ пункта по-прежнему решает sidebar_pages: адрес без пункта в списке ничего не добавляет.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"sidebar_links":{"agents":"/base/"}}'

{
  "success": true,
  "templates": {
    "footer": null,
    "posts_empty": null,
    "documents_view": null,
    "agents_catalog": { "title": { "ru": "Помощники", "en": "Assistants" } },
    "sidebar_links": { "agents": "/base/" },
    "sidebar": null
  }
}

Карта сливается с сохранённой по пунктам: присланный пункт меняет адрес, остальные остаются; "agents": null или пустой адрес снимает адрес пункта. "sidebar_links": null или {} возвращают все пункты внутрь чата. До 26.09.2026 карта заменялась целиком. Текущее значение отдаёт GET /assistants/{assistantId}/templates в templates.sidebar_links.

HTTP	Когда
200	Записано, в ответе весь контейнер шаблонов.
422	Больше 20 ключей или адрес длиннее 1024: `{"success":false,"errors":{…}}`.

Задержка перед ответом

Искусственная очередь перед ответом модели: человек видит обратный отсчёт и предложение платного доступа без очереди, а после ответа — приписку, сколько он ждал. По умолчанию выключена; при включении ждут только анонимные посетители. Владелец ассистента не ждёт никогда.

Получить задержку

GET /assistants/{assistantId}/delay

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

{
  "success": true,
  "delay_enabled": false,
  "delay_min_sec": 3,
  "delay_max_sec": 5,
  "delay_skip_paid": true,
  "delay_skip_auth": true,
  "delay_text": null,
  "delay_text_locales": {},
  "delay_note_text": null,
  "delay_note_text_locales": {}
}

Свойства задержки

Свойство	Тип	Описание
`delay_enabled`	boolean	Включить задержку. По умолчанию `false`; пока выключено, остальное не действует. `null` возвращает `false`.
`delay_min_sec`	number, 0–60	Нижняя граница, секунды. Округляется до 0,1. По умолчанию 3, `null` возвращает 3.
`delay_max_sec`	number, 0–60	Верхняя граница. По умолчанию 5, `null` возвращает 5. Задержка каждый раз случайная в диапазоне. Если нижняя окажется больше верхней, сервер поменяет их местами.
`delay_skip_paid`	boolean	Платящие не ждут. По умолчанию `true`, `null` возвращает `true`.
`delay_skip_auth`	boolean	Вошедшие не ждут. По умолчанию `true`, `null` возвращает `true`.
`delay_text`	string или null, до 1000	Текст во время ожидания на языке по умолчанию. Пусто — встроенный текст.
`delay_note_text`	string или null, до 1000	Приписка к ответу после ожидания; `{N}` заменяется числом секунд. Пусто — встроенный текст.
`delay_text_locales`	object	Переводы `delay_text`: `{"en": "…"}`, до 1000 символов на язык.
`delay_note_text_locales`	object	Переводы `delay_note_text`.

Изменить задержку

PUT /assistants/{assistantId}/delay

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь. Id ассистента.
`strict`	boolean	нет	Тело или строка запроса. `true` — незнакомое поле даёт 422.
остальные	—	нет	Тело, JSON. Свойства задержки.

Переводы (*_locales) сливаются с сохранёнными: присланные языки заменяются, остальные остаются, пустая строка удаляет язык.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/delay" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delay_enabled": true,
    "delay_min_sec": 3,
    "delay_max_sec": 5,
    "delay_text": "Вы в бесплатной очереди. С подпиской — без ожидания.",
    "delay_note_text_locales": {"en": "Answered via the free queue in {N}s."}
  }'

{
  "success": true,
  "applied": ["delay_enabled", "delay_min_sec", "delay_max_sec", "delay_text", "delay_note_text_locales"],
  "ignored": []
}

HTTP	Когда
200	Записано.
404	Ассистента нет или к нему нет доступа.
422	Ошибка валидации: `{"success":false,"errors":{"delay_max_sec":["The delay max sec field must not be greater than 60."]}}`.
422	`strict=true` и незнакомое поле.

Дальше

Модели — модели текста, картинок и видео.
Каталог «Помощники» — что показывает пункт «Помощники».
Шаблоны и подвал — контейнер templates, где лежат адреса пунктов.