Настройки бота и шапка
Идентичность ассистента и всё, что видно в шапке чата: имя, аватар, стиль ответов, логотип, дисклеймер. Плюс системный промпт и переменные в нём.
Настройки бота — это один большой объект ассистента, который читается GET /assistants/{assistantId}/bot и пишется PUT /assistants/{assistantId}/bot. Запись частичная: меняется только то, что пришло в теле. Системный промпт дополнительно вынесен в отдельный метод /system-prompt.
Во всех примерах:
BASE=https://framesuite.app/api/v1
KEY=user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ASSISTANT=53
Настройки бота
Получить настройки бота
Возвращает имя, аватар, стиль ответов, логотипы шапки, режим агента, панель окна входа и несколько полей приветствия.
GET /assistants/{assistantId}/bot
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
assistantId | integer | да | Путь. Id ассистента. Доступен владельцу и тем, кому ассистент открыт. |
curl -s "$BASE/assistants/$ASSISTANT/bot" \
-H "Authorization: Bearer $KEY"
{
"success": true,
"name": "bota.chat",
"bot_name": "Новый ассистент",
"bot_avatar": "default",
"avatar_type": "persona",
"persona_variant": "obsidian",
"bot_gender": null,
"interface_locale": null,
"thinking_text": "Думаю...",
"response_style": "text",
"primary_color": null,
"documents_empty_icon": null,
"header_logo": null,
"header_logo_dark": null,
"header_icon": null,
"header_icon_dark": null,
"ai_model": "default-model",
"credit_multiplier": 1.5,
"currency": "RUB",
"billing_mode": "tokens",
"system_prompt": "",
"welcome_message": "Чем могу помочь?",
"welcome_avatar": null,
"quick_actions": [],
"sticky_first_suggestions": false,
"commands_cache_enabled": true,
"agent_system_prompt": null,
"agent_reasoning": true,
"agent_post": false,
"agent_post_system_prompt": null,
"agent_post_first_only": false,
"agent_post_use_selected_model": false,
"agent_post_reasoning": false,
"auth_panel_enabled": false,
"auth_panel_title": null,
"auth_panel_subtitle": null,
"auth_features_title": null,
"auth_features": [],
"auth_reviews": [],
"auth_locales": {},
"bot_locales": {
"en": { "bot_name": "bota.chat", "bot_avatar": "default", "bot_gender": null },
"de": { "bot_name": "bota.chat", "bot_avatar": "default", "bot_gender": null },
"…": "…"
}
}
bot_locales — языковые версии имени, аватара, логотипа шапки и пунктов боковой панели, см. «Языковые версии: bot_locales» ниже. Если их нет — {}.
В ответе нет welcome_subtitle, header_note, input_placeholder, welcome_sections и welcome_mode, хотя PUT /bot их принимает. Читайте их через GET /assistants/{assistantId}/welcome — см. Первые экраны.
| HTTP | Когда |
|---|---|
| 200 | Настройки отданы. |
| 401 | Нет ключа или ключ неверный. |
| 404 | Ассистента нет или к нему нет доступа: {"success":false,"error":"Project not found or access denied"}. |
Изменить настройки бота
Частичное обновление: присылайте только поля, которые меняете. Незнакомые поля не пишутся и перечисляются в ignored; с strict=true (в теле или в строке запроса) незнакомое поле даёт 422 и ничего не пишется. Весь запрос проверяется до записи: если не прошло хоть одно поле, в том числе неизвестная ai_model, не записывается ничего — ни настройки, ни переводы.
PUT /assistants/{assistantId}/bot
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
assistantId | integer | да | Путь. Id ассистента. |
strict | boolean | нет | Тело или строка запроса. true — незнакомые поля дают 422 unknown_fields. |
| остальные | — | нет | Тело, JSON. Поля из таблицы свойств ниже. |
curl -s -X PUT "$BASE/assistants/$ASSISTANT/bot" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"thinking_text":"Думаю..."}'
{
"success": true,
"applied": ["thinking_text"],
"ignored": [],
"message": "Bot settings updated"
}
С незнакомым полем без strict запись проходит, но ответ предупреждает:
{
"success": true,
"applied": ["thinking_text"],
"ignored": ["bot_title"],
"message": "Bot settings updated",
"warning": "Some fields were ignored: bot_title"
}
applied — поля, которые записаны. Поля приветствия, пришедшие в этом запросе, сервер в той же транзакции переносит и на приветственный экран по умолчанию; остальные экраны не трогаются.
| HTTP | Когда |
|---|---|
| 200 | Записано. Смотрите applied и ignored. |
| 404 | Ассистента нет или к нему нет доступа. |
| 422 | Ошибка валидации: {"success":false,"errors":{"primary_color":["The primary color field format is invalid."]}}. |
| 422 | strict=true и есть незнакомое поле: {"success":false,"error":"unknown_fields","message":"Unknown fields: bot_title","ignored":["bot_title"]}. |
| 422 | ai_model не найден среди моделей: {"success":false,"error":"Invalid AI model"}. Остальные поля запроса тоже не записываются. |
| 422 | Ошибка в языковой версии: ключ ошибки — полный путь, {"success":false,"errors":{"bot_locales.en.bot_gender":["The selected bot_locales.en.bot_gender is invalid."]}}. |
null в полях, у которых в базе нет пустого значения (ai_model, credit_multiplier, currency, billing_mode, response_style), ничего не меняет: поле остаётся как было.
Переводы приветствия: слияние по языкам
welcome_locales сливается с сохранённой картой: язык, которого нет в теле, остаётся как был; в присланном языке меняются только присланные поля. "de": null удаляет перевод на этом языке. Языки, которых нет в списке языков ассистента, отбрасываются.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/bot" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"welcome_locales": {"en": {"header_note": "AI can make mistakes."}, "de": null}}'
Здесь у английского меняется только дисклеймер, немецкий перевод удаляется, остальные языки не трогаются.
Языковые версии: bot_locales
bot_locales — карта «язык → поля идентичности ассистента». Чат на языке посетителя берёт отсюда имя, аватар, логотип шапки и пункты боковой панели, а где поля нет — значение верхнего уровня. Имя, аватар и логотип при отсутствии версии своего языка берутся из версии en; sidebar_pages действует только на своём языке, без подстановки en. Тот же объект пишет слайд «Бот» в дашборде.
| Поле языка | Тип | Описание |
|---|---|---|
bot_name | string, до 100 | Имя ассистента на этом языке. |
bot_avatar | string, до 255 | Имя файла аватара (как у bot_avatar верхнего уровня) или default. |
bot_gender | string | male или female. |
header_logo, header_logo_dark | string, до 1024 | Логотип шапки на этом языке: http(s)://… или путь от корня (/storage/…). |
header_icon, header_icon_dark | string, до 1024 | Знак свёрнутой панели на этом языке, те же правила. |
sidebar_pages | array, до 20 | Пункты боковой панели на этом языке: id страниц, строки до 64 символов, как sidebar_pages в /features. [] — на этом языке пунктов нет. Повторы и пустые убираются. |
Карта сливается с сохранённой по языкам и полям, как welcome_locales: неприсланный язык и неприсланное поле остаются; null или "" в поле снимает его (действует значение верхнего уровня); "<язык>": null удаляет весь язык; языки, которых нет в списке языков ассистента, отбрасываются. Проверка идёт до записи вместе с остальными полями PUT /bot.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/bot" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"bot_locales": {"en": {"bot_name": "Anastasia", "header_logo": "/storage/welcome-cards/logo-en.svg"}, "de": null}}'
Здесь у английского меняются имя и логотип, остальные поля en остаются, немецкая версия удаляется целиком. avatar_type: "none" сбрасывает bot_avatar в default и во всех языковых версиях.
Свойства настроек бота
Имя, аватар и стиль ответов
| Свойство | Тип | Описание |
|---|---|---|
name | string, до 255 | Внутреннее название ассистента для дашборда. Посетитель его тоже может увидеть — например, в заголовке вкладки браузера. Пустая строка игнорируется: авто-название вида «Новый ассистент #K42» так не стереть. |
bot_name | string, до 100 | Публичное имя ассистента: им он подписывает ответы в чате. |
avatar_type | string | persona — сгенерированный персонаж (по умолчанию), custom — загруженная картинка, none — без аватара. При none сервер сбрасывает bot_avatar в default и в самом ассистенте, и в языковых версиях. |
persona_variant | string, до 20 | Вариант персонажа, по умолчанию obsidian. Пустое значение не пишется. |
bot_gender | string или null | male или female. |
bot_avatar | string, до 255 | Имя файла загруженного аватара (без пути и расширения) или default — первая буква имени. null или пустая строка превращаются в default. Картинку загружает POST /bot/avatar. |
thinking_text | string, до 100 | Текст, пока ассистент готовит ответ, например «Думаю…». |
response_style | string | text (по умолчанию) — ответ сплошным текстом, messenger — короткими пузырями, как в мессенджере. |
bot_locales | object | Языковые версии имени, аватара, пола, логотипов и пунктов боковой панели. Сливается по языкам и полям — см. «Языковые версии: bot_locales». |
interface_locale | string или null | Принудительный язык чата: ru или en. Действует и на интерфейс, и на контент (приветствие, агенты, пейволл) и перебивает ?locale= и язык браузера; уступает только языку страницы сайта, в которую встроен чат. auto, пустая строка или null — определять по посетителю (по умолчанию). |
Шапка чата
| Свойство | Тип | Описание |
|---|---|---|
header_note | string, до 300 | Дисклеймер по центру шапки. Только запись: в GET /bot его нет, читайте через GET /welcome. Подробнее — в разделе «Дисклеймер в шапке» ниже. |
header_logo | string или null, до 1024 | Логотип в верхней строке развёрнутой боковой панели (светлая тема). Клик открывает новый чат. Абсолютный http(s):// или путь от корня (/storage/...). SVG или прозрачный PNG высотой от 40 px. Пустое значение снимает логотип. |
header_logo_dark | string или null, до 1024 | Тот же логотип для тёмной темы. Пусто — в тёмной теме показывается header_logo. |
header_icon | string или null, до 1024 | Квадратный знак для свёрнутой боковой панели (светлая тема), SVG или PNG от 48 px. Пусто — в свёрнутой панели логотипа нет, полный логотип в знак не ужимается. |
header_icon_dark | string или null, до 1024 | Знак для тёмной темы. Пусто — берётся header_icon. |
primary_color | string или null | Основной цвет ассистента #RRGGBB, сохраняется в нижнем регистре. Красит активную вкладку переключателя категорий на приветственном экране. Пустое значение возвращает цвета темы. |
documents_empty_icon | string или null, до 1024 | Картинка пустой панели «Документы» вместо значка папки. PNG с прозрачным фоном, квадрат 256–512 px. |
Файлы для логотипов загружайте через POST /assistants/{assistantId}/upload/image с context=card — там же принимается SVG, см. Загрузка файлов.
Приветствие (дублирует /welcome)
PUT /bot принимает поля приветствия с теми же правилами, что и PUT /welcome. Это наследие: для новых интеграций используйте Первые экраны.
| Свойство | Тип | Описание |
|---|---|---|
welcome_message | string, до 500 | Заголовок приветственного экрана. |
welcome_subtitle | string, до 500 | Подзаголовок. |
input_placeholder | string, до 255 | Подсказка в поле ввода. |
welcome_avatar | string, до 1024 | Картинка над заголовком приветствия: полный путь (/storage/welcome-cards/...) или URL. Пусто — картинки нет. То же поле принимает PUT /welcome. |
welcome_sections | array, до 10 | Секции агентов на приветственном экране, формат — на странице Первые экраны. |
welcome_mode | string | new_chat или message — как клик по агенту открывает диалог. null — вернуть new_chat. |
welcome_collapsed_limit | integer, 1–999 | Сколько карточек агентов видно до кнопки «Показать больше». 999 (по умолчанию) — кнопки нет, null — вернуть 999. |
welcome_locales | object | Переводы полей приветствия по языкам: welcome_message, welcome_subtitle, header_note, welcome_start_message, input_placeholder, welcome_sections. Сливается с сохранённой картой, "<язык>": null удаляет язык — см. выше. |
quick_actions | array, до 10 | Устаревшие быстрые кнопки: label (обязательно, до 50), prompt (до 500), icon (до 50), action — send, image, diagram, voice, plot, search, document. |
sticky_first_suggestions | boolean | Варианты ответа из первого сообщения остаются на экране и после ответа человека. |
commands_cache_enabled | boolean | Авто-кэш ответов на команды: повторный запуск той же команды отдаётся без обращения к модели. |
welcome_start_message на верхнем уровне у ассистента не хранится: метод его не пишет и возвращает в ignored. Стартовое сообщение режима message задаётся по языкам — welcome_locales.<язык>.welcome_start_message или ключ welcome.welcome_start_message в /i18n.
Модель и оплата
Эти поля — наследие слайда «Бот». Для моделей есть отдельный метод, для оплаты — Пейволл и тарифы.
| Свойство | Тип | Описание |
|---|---|---|
ai_model | string, до 50 | Стартовая модель. Принимается default-model, auto-free, любой id вида vendor/model и старые короткие id. Иначе 422 Invalid AI model. |
credit_multiplier | number, 1–10 | Старый множитель стоимости, на списание не влияет. |
currency | string | RUB или USD. |
billing_mode | string | tokens или subscription. |
Промпты и режим агента
| Свойство | Тип | Описание |
|---|---|---|
system_prompt | string, до 50000 | Общий системный промпт ассистента. То же поле, что у /system-prompt. |
agent_system_prompt | string или null, до 50000 | Отдельный промпт для режима агента. Пустая строка сохраняется как null. |
agent_reasoning | boolean | Рассуждения модели в режиме агента. |
agent_post | boolean | Дописывание после ответа: второй проход модели по готовому ответу. |
agent_post_system_prompt | string или null, до 50000 | Промпт дописывания. Пустая строка — null. |
agent_post_first_only | boolean | Дописывать только первый ответ диалога. |
agent_post_use_selected_model | boolean | Дописывать той же моделью, что выбрал человек. |
agent_post_reasoning | boolean | Рассуждения на проходе дописывания. |
Булевы поля принимают true, false, 1, 0, "true", "1".
Боковая панель окна входа
Панель рядом с формой входа: заголовок, список возможностей и отзывы.
| Свойство | Тип | Описание |
|---|---|---|
auth_panel_enabled | boolean | Показывать панель. Общая для всех языков. |
auth_panel_title | string, до 200 | Заголовок. |
auth_panel_subtitle | string, до 500 | Подзаголовок. |
auth_features_title | string, до 200 | Заголовок списка возможностей. |
auth_features | array, до 10 | Возможности: title (до 200), icon (до 50), icon_bg (до 50). |
auth_reviews | array, до 10 | Отзывы: name (до 100), role (до 100), text (до 1000), avatar (до 500), rating (0–5). |
auth_locales | object | Переводы по языкам: {"en": {"auth_panel_title": "...", "auth_features": [...]}}. Незаданное поле языка берётся из основных. Сохраняется как прислано. |
Шапка чата
Шапка складывается из настроек разных разделов. Сводка, чтобы не искать:
| Что в шапке | Чем управляется |
|---|---|
| Логотип и знак в боковой панели | header_logo, header_logo_dark, header_icon, header_icon_dark в PUT /bot |
| Дисклеймер по центру | header_note в PUT /bot, PUT /welcome или PUT /welcome-screens/{screenId} |
| Переключатель языка | Появляется, когда у ассистента больше одного языка сайта — Языки и переводы |
| Значок поддержки | tickets_enabled в /features |
| Кнопка голосового режима | capability_voice_mode в /features |
| «Поделиться» в меню | Есть, только когда к ассистенту привязан свой домен — Домены |
| Превью и название открытого агента | Картинка и название агента — Агенты |
Логотип: правила подстановки
Тёмная тема берёт *_dark, если он задан, иначе светлый вариант. Свёрнутая боковая панель показывает header_icon (или header_icon_dark), а если знака нет — логотипа там нет вовсе. Тему чат берёт у системы посетителя.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/bot" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"header_logo": "https://framesuite.app/storage/welcome-cards/logo.svg",
"header_logo_dark": "https://framesuite.app/storage/welcome-cards/logo-dark.svg",
"header_icon": "https://framesuite.app/storage/welcome-cards/icon.svg"
}'
У каждого языка может быть свой логотип, своё имя и свой аватар ассистента — поле bot_locales в PUT /bot, см. «Языковые версии: bot_locales». Логотип языка подставляется парой: если в версии языка задан светлый вариант, тёмный берётся тоже из неё (пустой — как светлый), а не с верхнего уровня.
Дисклеймер в шапке
Мелкая приглушённая строка по центру шапки — для оговорок вроде «Независимый сервис, не связан с разработчиками моделей». Видна только на приветственном экране: после первого сообщения, в документе и в голосовом режиме её нет. Длинный текст обрезается многоточием, полный остаётся во всплывающей подсказке; на узком экране строка занимает не больше 60% ширины шапки.
Базовое поле header_note — текст на языке ассистента по умолчанию. Переводы — welcome_locales.<язык>.header_note или ключ welcome.header_note в /i18n. Пустая строка — дисклеймера нет. У каждого приветственного экрана он может быть свой.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/welcome" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"header_note":"Независимый ИИ-ассистент. Не связан с OpenAI, Google и другими разработчиками моделей."}'
Переносы строк в приветствии
В welcome_message, welcome_subtitle и input_placeholder (и в их переводах) можно ставить маркеры переноса. Сам маркер посетитель не видит ни в чате, ни на статичном первом кадре.
||— перенос только на узком экране (меньше 768 px), на десктопе пробел.\\— перенос только на десктопе (от 768 px), на узком экране пробел.|— перенос всегда.
В тесных местах (заголовки секций, подписи карточек) маркер превращается в пробел. В JSON обратный слэш экранируется, поэтому десктопный перенос в теле запроса пишется четырьмя символами \\\\. Для одиночного мобильного переноса проще ||.
curl -s -X PUT "$BASE/assistants/$ASSISTANT/welcome" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"welcome_subtitle":"Спросите про еду, детей или быт.||Ответ за 30 секунд."}'
Аватар бота
Загрузить аватар бота
Загружает картинку аватара ассистента. Сервер обрезает её по центру в квадрат 256×256, сохраняет в WebP и PNG, удаляет прежний аватар и пишет имя файла в bot_avatar. Для порядка поставьте и avatar_type: "custom"; чат прячет аватар только при avatar_type: "none".
POST /assistants/{assistantId}/bot/avatar
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
assistantId | integer | да | Путь. Id ассистента. |
avatar | file | да | Тело, multipart/form-data. JPEG, PNG или WebP, до 10 МБ. |
curl -s -X POST "$BASE/assistants/$ASSISTANT/bot/avatar" \
-H "Authorization: Bearer $KEY" \
-F "avatar=@avatar.png"
{
"success": true,
"avatar": "bot_project_53_1790000000",
"message": "Avatar updated"
}
Снять аватар — PUT /bot с "bot_avatar": null (станет default, первая буква имени) или "avatar_type": "none".
| HTTP | Когда |
|---|---|
| 200 | Аватар заменён. |
| 404 | Ассистента нет или к нему нет доступа. |
| 422 | Нет файла или не тот формат: {"success":false,"error":"The avatar field is required."}. |
| 500 | Картинку не удалось обработать: {"success":false,"error":"Failed to process image"}. Прежний аватар при этом остаётся: его файлы удаляются только после записи нового. |
Системный промпт
Системный промпт — роль и правила ассистента на весь разговор. Когда активен агент со своим промптом, действует промпт агента, см. Агенты.
Получить системный промпт
GET /assistants/{assistantId}/system-prompt
curl -s "$BASE/assistants/$ASSISTANT/system-prompt" \
-H "Authorization: Bearer $KEY"
{
"success": true,
"system_prompt": "Ты — консультант сервиса…"
}
Пустой промпт отдаётся пустой строкой.
Заменить системный промпт
Записывает промпт целиком. Поле system_prompt обязательно в теле: без него запрос отбивается 422 и промпт не трогается. Очистить промпт — явный null или пустая строка.
PUT /assistants/{assistantId}/system-prompt
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
assistantId | integer | да | Путь. Id ассистента. |
system_prompt | string или null | да | Тело. До 50000 символов. null или "" — очистить промпт. |
curl -s -X PUT "$BASE/assistants/$ASSISTANT/system-prompt" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"system_prompt":"Ты — консультант сервиса {{BOT_NAME}}. Сегодня {{DATE}}."}'
{
"success": true,
"message": "System prompt updated"
}
| HTTP | Когда |
|---|---|
| 200 | Записано. |
| 404 | Ассистента нет или к нему нет доступа. |
| 422 | Поля нет в теле (пустое тело, опечатка в имени): {"success":false,"errors":{"system_prompt":["The system prompt field must be present."]}}. |
| 422 | Не строка или длиннее 50000: {"success":false,"errors":{"system_prompt":["The system prompt field must be a string."]}}. |
Переменные в промпте
В промпт можно вставить переменную {{ИМЯ}}: при каждом ответе она заменяется текущим значением. Регистр не важен, пробелы внутри скобок допустимы. Неизвестное имя остаётся в тексте как есть — так видна опечатка и не ломаются чужие фигурные скобки, например JSON внутри промпта. Условий и циклов нет, только замена.
| Переменная | Чем заменяется |
|---|---|
{{BOT_NAME}} | Имя ассистента. |
{{PROJECT_NAME}} | Название ассистента (поле name). |
{{PARTNER_PERCENT}} | Процент партнёрской программы ассистента. |
{{USER_NAME}} | Имя собеседника. |
{{USER_EMAIL}} | Почта собеседника. |
{{USER_LOCALE}} | Код языка собеседника. |
{{USER_LANGUAGE}} | Язык собеседника словом по-английски, например English. Неизвестный код — пусто. |
{{IS_GUEST}} | да — анонимный, нет — вошёл. |
{{CREDITS}} | Остаток кредитов собеседника у этого ассистента. |
{{HAS_PAID}} | да или нет — платил ли когда-нибудь. |
{{SUBSCRIPTION}} | Статус подписки (active, past_due, cancelled) или нет. |
{{SUBSCRIPTION_SINCE}} | Начало оплаченного периода, YYYY-MM-DD. |
{{SUBSCRIPTION_UNTIL}} | Конец оплаченного периода, YYYY-MM-DD. |
{{SUBSCRIPTION_CREDITS}} | Кредитов в периоде подписки. |
{{SUBSCRIPTION_CANCELLED}} | да — подписка отменена и не продлится. |
{{DATE}} | Сегодняшняя дата в часовом поясе собеседника, YYYY-MM-DD. |
{{TIME}}, {{DATETIME}}, {{TIMEZONE}} | Время, дата со временем и часовой пояс собеседника. Без пояса браузера — UTC. |
Где работают: общий системный промпт ассистента, промпт агента, заготовленный первый ответ агента (prepared_response) и заготовленные ответы на варианты-чипы. В заготовках, которые уходят человеку минуя модель, доступен сокращённый набор: BOT_NAME, PROJECT_NAME, PARTNER_PERCENT, USER_NAME, USER_EMAIL, USER_LOCALE, USER_LANGUAGE, IS_GUEST, CREDITS, HAS_PAID, DATE (дата там серверная). В подписях кнопок и текстах самих чипов переменные не раскрываются.
Дальше
- Первые экраны (welcome) — заголовок, секции и переводы приветствия.
- Языки и переводы — перевод дисклеймера, приветствия и агентов через
/i18n. - Модели — стартовая модель и набор моделей в чате.