Шаблоны и подвал в API bota.chat: footer, панели, каталог

Что внутри контейнера

Все настройки раздела лежат в одном JSON-объекте templates ассистента. Каждый ключ — отдельная настройка, методы меняют только присланные ключи.

Ключ	Что настраивает
`footer`	Подвал под всеми приветственными экранами: реквизиты, оферта, ссылки.
`posts_empty`	Пустое состояние панели «План публикаций».
`documents_view`	Вид панели документов в боковой панели чата: список или плитка.
`agents_catalog`	Тексты каталога «Помощники»: заголовок, подписи вкладок, скрытые категории.
`sidebar_links`	Свои адреса пунктов боковой панели: пункт ведёт на страницу сайта вместо страницы внутри чата.
`sidebar`	Служебные настройки боковой панели: тег агентов каталога «Помощники» и категория страницы «Шаблоны документов».

Подвал

Юридический текст со ссылками, который владелец кладёт один раз. Показывается внизу каждого приветственного экрана ассистента — на основном и на отдельных (?w=, ?screen=). Шрифт мельче основного, ширина как у поля ввода. Мало контента — подвал прижат к низу экрана, много — уезжает вниз и виден при прокрутке. Не задан — блока нет вовсе.

Свойства подвала

Свойство	Тип	Описание
`footer.html`	string	Базовый текст, до 5000 знаков. Считается текстом на языке ассистента по умолчанию.
`footer.locales`	object	Переводы: «код языка → `{"html": "…"}`», до 5000 знаков на язык. Язык должен быть включён у ассистента.

Язык посетителя подбирается так же, как у приветствия: перевод его языка → базовый текст, если он говорит на языке ассистента → перевод en, если английский включён у ассистента → базовый текст.

Очистка html

Весь html проходит очистку на сервере до записи, в базе лежит уже безопасный текст. Присланное может не совпасть с сохранённым — сверяйте по GET.

Что	Как обрабатывается
`p`, `br`, `a`, `strong`, `b`, `em`, `i`, `u`, `small`, `span`, `ul`, `ol`, `li`, `hr`	Остаются.
`script`, `style`, `link`, `meta`, `iframe`, `object`, `embed`, `svg`, `img`, `picture`, `video`, `audio`, `canvas`, `form`, `input`, `button`, `select`, `textarea`, `template`, `noscript` и подобные	Удаляются вместе с содержимым.
Прочие теги (`div`, `h1`…)	Тег снимается, текст остаётся.
Атрибуты	Выбрасываются все, кроме `href` у `<a>`.
`href`	Разрешены `http`, `https`, `mailto`, `tel`, относительные ссылки и якоря. `javascript:`, `data:` — ссылка снимается, текст остаётся.
Ссылки	Получают `target="_blank"` и `rel="noopener noreferrer"` принудительно.

Переменные-действия

В тексте подвала можно поставить переменную, которая превращается в ссылку, открывающую окно внутри чата вместо перехода:

{{ACTION_SUPPORT}}
{{ACTION_SUPPORT|Написать в поддержку}}

После | — подпись ссылки: только текст, до 80 знаков, угловые скобки, кавычки и = вырезаются. Пробелы вокруг имени и подписи не важны. Переменная хранится текстом, а ссылку из неё делает сервер при выдаче, поэтому свой атрибут или скрипт через неё не протащить.

Переменная	Что делает	Подпись по умолчанию
`{{ACTION_SUPPORT}}`	Открывает окно обращений в поддержку. Работает, если обращения включены у ассистента (`tickets_enabled`, см. Поддержка и обращения).	Написать в поддержку

Неизвестное имя ({{ACTION_FOO}}) остаётся в тексте как есть — опечатку сразу видно на экране.

В GET переменная видна в двух видах: в templates.footer.html — исходным текстом, в resolved.footer_html — готовой ссылкой:

<a href="#action-support" data-footer-action="support" role="button">Написать в поддержку</a>

Удалить подвал

Целиком — "footer": null или "footer": {}. Пустой или невидимый html ("html": "", <p></p>) снимает только базовый текст: из-за слияния переводы остаются, и подвал исчезает, только если переводов нет. Чтобы убрать один перевод, пришлите его как null: {"footer": {"locales": {"en": null}}}.

Пустое состояние панели постов

Панель «План публикаций» (агент с config.panel = "posts", см. Свойства config), пока в ней нет постов, показывает значок, заголовок и подпись. posts_empty заменяет их своими; при записи объект сливается с сохранённым по ключам.

Свойство	Тип	Описание
`posts_empty.icon`	string	Значок из списка: `CalendarDays`, `ClipboardList`, `FileText`, `Hash`, `Image`, `Inbox`, `LayoutList`, `Megaphone`, `MessageSquare`, `Newspaper`, `PenLine`, `PlayingCardsFan` (по умолчанию), `Rocket`, `Send`, `Share2`, `Sparkles`, `Sticker`.
`posts_empty.image`	string	Адрес картинки вместо значка, до 500 знаков. Главнее значка.
`posts_empty.title`	object	«Код языка → заголовок», до 160 знаков.
`posts_empty.text`	object	«Код языка → подпись», до 1000 знаков.

Текст подбирается так: язык посетителя → en → язык ассистента. Нет строки — берётся текст по умолчанию из словаря чата. Языки должны быть включены у ассистента.

Вид панели документов

documents_view — как боковая панель чата показывает файлы посетителя: list (по умолчанию, дерево с иконками) или grid (плитка с превью). list и null не хранятся — ключ снимается.

Тексты каталога «Помощники»

agents_catalog меняет заголовок, подзаголовок, подпись пункта в боковой панели и плейсхолдер поиска каталога агентов, подписи его вкладок и список скрытых категорий. Объект сливается с сохранённым по ключам: {"agents_catalog": {"title": {"en": "Helpers"}}} меняет только английский заголовок. null у языка или поля удаляет его, пустые строки выбрасываются. Исключение — hidden_categories: список заменяется целиком. "agents_catalog": null или {} возвращает всё к текстам по умолчанию.

Свойство	Тип	Описание
`title`, `subtitle`, `sidebar_label`, `search_placeholder`	object	«Код языка → строка», до 500 знаков.
`categories`	object	«Ключ категории → код языка → подпись вкладки», до 100 знаков.
`hidden_categories`	array	Ключи категорий, которых в каталоге нет, до 100. На приветственном экране они остаются.

Подробно, с порядком подбора подписей и примерами, — на странице Каталог «Помощники».

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

sidebar — объект из двух ключей. Слияние по ключам: неприсланный ключ остаётся как был, "" или null снимает ключ. Пустой объект из контейнера убирается, и GET отдаёт sidebar: null.

Свойство	Тип	Описание
`sidebar.agents_tag`	string	Тег каталога «Помощники», до 64 знаков. Пункт `agents` боковой панели и адрес `?lib=agents` без категории показывают только агентов, у которых этот тег есть в `config.tags` (см. Свойства config). Нормализуется как теги агента: нижний регистр, без пробелов по краям. То же поле в визарде стоит под переключателем «Помощники»; в теле можно прислать и плоский синоним `sidebar_agents_tag`.
`sidebar.templates_category`	string	Категория агентов для страницы «Шаблоны документов» (`samples`), до 191 знака. То же, что `sidebar_templates_category` в `PUT /features` (Возможности, сайдбар и задержка).

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

sidebar_links превращает пункт боковой панели чата в обычную ссылку на страницу сайта: например, «Помощники» ведут на страницу каталога на вашем сайте, а не открывают каталог внутри чата. Объект «идентификатор пункта → адрес», до 20 пунктов.

Пункт	Что это
`agents`	Каталог «Помощники».
`samples`	Шаблоны документов.
`documents`	Документы посетителя.
`tickets`	Поддержка.

Адрес — полный http(s)://… (хранится как есть) или путь от корня сайта, до 1024 знаков. Путь приводится к виду со слэшами в начале и в конце: base/canva сохранится как /base/canva/. Путь открывается на домене, где работает чат: на сайте со встроенным чатом или на своём домене ассистента; на служебном адресе /f/{frame_slug} — на своём домене ассистента. Адреса с пробелами, с другой схемой (javascript:, mailto:) и вида //host отбрасываются. Объект сливается по пунктам: неприсланный пункт остаётся, null или пустой адрес снимает пункт. "sidebar_links": null или {} возвращают все пункты внутрь чата. Какие пункты вообще есть в панели, задаёт sidebar_pages в Возможностях.

Методы

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

Отдаёт контейнер как он лежит в базе и то, что увидит посетитель на указанном языке.

GET /assistants/{assistantId}/templates

Параметр	Тип	Обяз.	Описание
`assistantId`	int	да	Путь.
`locale`	string	нет	Строка запроса. Язык для блока `resolved`; по умолчанию язык ассистента.

curl -s "$BASE/assistants/$ASSISTANT/templates?locale=ru" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "locale": "ru",
  "locales": ["ru", "en", "kk", "…"],
  "default_locale": "ru",
  "templates": {
    "footer": null,
    "posts_empty": null,
    "documents_view": null,
    "agents_catalog": {
      "title": {"en": "Assistants", "ru": "Помощники"},
      "sidebar_label": {"en": "Assistants", "ru": "Помощники"},
      "search_placeholder": {"en": "Search assistants", "ru": "Поиск помощников"},
      "categories": {
        "Изображения": {"en": "Images"},
        "Исследования и анализ": {"en": "Research & Analysis"}
      },
      "hidden_categories": ["Создайте изображения"]
    },
    "sidebar_links": {"agents": "/base/"},
    "sidebar": null
  },
  "resolved": {
    "footer_html": null,
    "posts_empty": {"icon": "PlayingCardsFan", "title": null, "text": null, "image": null},
    "documents_view": "list"
  }
}

Поле	Описание
`templates`	Контейнер как в базе (html подвала уже очищен). Не заданный ключ — `null`.
`resolved.footer_html`	Html подвала на языке `locale` с развёрнутыми переменными-действиями; `null` — подвала нет.
`resolved.posts_empty`	Пустое состояние панели постов на языке `locale`; `null` в полях — текст по умолчанию.
`resolved.documents_view`	Действующий вид панели документов.

HTTP	Когда
404	Ассистента нет или нет доступа.
422	Параметр строки запроса пришёл массивом (`?locale[]=en`): `{"success": false, "error": "invalid_query", "message": "Query parameters must be strings: locale", "errors": {"locale": ["…"]}}`.

Изменить раздел

Меняет только присланные ключи контейнера. Внутри footer, posts_empty, agents_catalog, sidebar_links и sidebar — слияние по ключам: прислали один перевод или одно поле — остальное остаётся, null удаляет ключ, пустая строка снимает значение. Списки (hidden_categories) заменяются целиком. null или {} вместо самого ключа сбрасывает настройку целиком ("footer": null удаляет подвал).

PUT /assistants/{assistantId}/templates

Параметр	Тип	Обяз.	Описание
`assistantId`	int	да	Путь.
`footer`	object или null	нет	Тело. `{"html": "…", "locales": {"en": {"html": "…"}}}`; `null` удаляет подвал.
`posts_empty`	object или null	нет	Тело. `null` или пустой объект возвращает текст по умолчанию.
`documents_view`	string или null	нет	Тело. `list` или `grid`.
`agents_catalog`	object или null	нет	Тело.
`sidebar_links`	object или null	нет	Тело. До 20 пунктов, адрес до 1024 знаков.
`sidebar`	object или null	нет	Тело. `{"agents_tag": "…", "templates_category": "…"}`, сливается по ключам.
`sidebar_agents_tag`	string или null	нет	Тело. Синоним `sidebar.agents_tag`; если пришли оба, берётся плоский.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "footer": {
      "html": "<p>ООО «Ромашка», ИНН 7700000000. <a href=\"https://example.com/offer\">Оферта</a> · {{ACTION_SUPPORT|Есть вопрос?}}</p>",
      "locales": {
        "en": {"html": "<p>Romashka LLC. <a href=\"https://example.com/offer\">Terms</a> · {{ACTION_SUPPORT|Questions?}}</p>"}
      }
    },
    "documents_view": "grid"
  }'

Ответ — весь контейнер после записи:

{
  "success": true,
  "templates": {
    "footer": {
      "html": "<p>ООО «Ромашка», ИНН 7700000000. <a href=\"https://example.com/offer\" target=\"_blank\" rel=\"noopener noreferrer\">Оферта</a> · {{ACTION_SUPPORT|Есть вопрос?}}</p>",
      "locales": {"en": {"html": "<p>Romashka LLC. …</p>"}}
    },
    "posts_empty": null,
    "documents_view": "grid",
    "agents_catalog": {"title": {"en": "Assistants", "ru": "Помощники"}, "…": "…"},
    "sidebar_links": {"agents": "/base/"},
    "sidebar": null
  }
}

Пустое состояние панели постов и адрес каталога на сайте:

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"posts_empty": {"icon": "Megaphone", "title": {"ru": "Постов пока нет", "en": "No posts yet"}, "text": {"ru": "Попросите ассистента составить план"}}, "sidebar_links": {"agents": "/base/"}}'

Каталог «Помощники» только из агентов с тегом customgpt:

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

В ответе — "sidebar": {"agents_tag": "customgpt"}; прежний templates_category, если был, остаётся рядом. Снять тег — {"sidebar": {"agents_tag": null}}.

HTTP	Когда
404	Ассистента нет или нет доступа.
422	Ошибка формы. Сообщения по-русски, например `{"success": false, "errors": {"footer": ["Поле footer должно быть объектом вида {\"html\": \"...\", \"locales\": {...}}."], "documents_view": ["Вид документов documents_view не из списка: list, grid."]}}`. Длиннее 5000 знаков — «Текст подвала длиннее 5000 символов.». Значок не из списка — «Значок posts_empty.icon не из списка: …». Тег длиннее 64 знаков — `{"success": false, "errors": {"sidebar.agents_tag": ["The sidebar.agents tag field must not be greater than 64 characters."]}}`.
422	Язык перевода не включён у ассистента: `{"success": false, "error": "locale_not_active", "message": "Язык 'xx' не включён у проекта. Сначала добавьте его через POST /assistants/{id}/locales."}`. Язык со значением `null` (удаление перевода) не проверяется.

Дальше

Первые экраны — экраны, под которыми стоит подвал.
Каталог «Помощники» — подробно про agents_catalog.
Поддержка и обращения — окно, которое открывает {{ACTION_SUPPORT}}.