Каталог «Помощники» в API bota.chat: категории, тексты, теги

Что такое каталог

Каталог — страница чата ?lib=agents: заголовок, подзаголовок, поле поиска, вкладки категорий и карточки агентов с аватаром, названием, описанием и строкой «От …». Вход не нужен. Клик по карточке открывает экран-профиль агента или его страницу на сайте, если у агента задан page_url.

Открыть каталог можно адресом или пунктом боковой панели:

https://framesuite.app/f/{frame_slug}?lib=agents
https://framesuite.app/f/{frame_slug}?lib=agents&tab=Изображения
https://framesuite.app/f/{frame_slug}?lib=agents&tag=customgpt

Пункт боковой панели включается значением "agents" в sidebar_pages ассистента — PUT /assistants/{assistantId}/features, см. Возможности, сайдбар и задержка.

Как агент попадает в каталог

Своих категорий у каталога нет — он берёт их с приветственного экрана. Агент показывается, если выполнены все условия:

Условие	Подробности
Категория агента есть на экране	Одна из `categories` агента совпадает с вкладкой секции-переключателя или с категорией секции-списка, у которой есть заголовок
Категория не скрыта	Её нет в `agents_catalog.hidden_categories`
Есть название	`label` на языке каталога не пустой
Подходит тег	Если задан отбор по тегу — у агента есть этот тег в `config.tags`

Вкладки идут в порядке экрана: сначала вкладки секций-переключателей, в том числе скрытых на приветственном экране, потом секции-списки с заголовком. Пустые вкладки не показываются. Так ассистенту можно завести категории каталога, не меняя витрину: добавьте на экран секцию-переключатель с нужными вкладками и скройте её — каталог вкладки подхватит. Секции и вкладки настраиваются на странице Первые экраны. Экран берётся из параметра w (или screen) адреса, домена или экрана по умолчанию.

Порядок карточек — order агентов. Описание карточки — subtitle, иначе первый абзац prepared_response без разметки (до 220 символов). Аватар — character_avatar, иначе image; нет картинки — пастельная заглушка. «От …» — profile_author, пусто — строки нет.

Поиск идёт на странице по названию, описанию и документу страницы агента page_markdown — поэтому его стоит заполнять, даже если на карточке его не видно.

Отбор по тегу

Каталог можно ограничить агентами с одним служебным тегом (config.tags, см. Свойства config): например, показывать только агентов в стиле кастомных GPT с тегом customgpt. Тег берётся из параметра ?tag= адреса, иначе из тега каталога ассистента — templates.sidebar.agents_tag. Он действует на пункт «Помощники» в боковой панели и на голый адрес ?lib=agents. В дашборде это поле под тумблером «Помощники в боковой панели», через API — PUT /assistants/{assistantId}/templates.

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`	string или null, до 64	Тег каталога. Приводится к виду тегов агента: нижний регистр, без пробелов по краям. `""` или `null` снимает тег — каталог показывает всех агентов. Плоский синоним в теле — `sidebar_agents_tag`
`sidebar.templates_category`	string или null, до 191	Соседний ключ того же объекта — категория страницы «Шаблоны документов», то же, что `sidebar_templates_category` в /features

Объект sidebar сливается по ключам: неприсланный ключ остаётся, остальные ключи контейнера templates не трогаются. Текущее значение — templates.sidebar в GET /templates (null, если ключей нет). Длиннее 64 символов — 422 {"success": false, "errors": {"sidebar.agents_tag": ["The sidebar.agents tag field must not be greater than 64 characters."]}}.

Тексты и вкладки: templates.agents_catalog

Тексты каталога и подписи вкладок хранятся в контейнере шаблонов ассистента, ключ agents_catalog. Читается и пишется методами GET и PUT /assistants/{assistantId}/templates, которые целиком описаны на странице Шаблоны и подвал. Здесь — только часть каталога.

Свойство	Тип	Описание
`title`	object	Заголовок страницы: «язык → строка», до 500 символов
`subtitle`	object	Подзаголовок, «язык → строка», до 500
`sidebar_label`	object	Подпись пункта в боковой панели, «язык → строка», до 500
`search_placeholder`	object	Подсказка в поле поиска, «язык → строка», до 500
`categories`	object	Подписи вкладок: «ключ категории → язык → строка», до 100 символов. Главнее подписей приветственного экрана
`hidden_categories`	array	Ключи категорий, которых в каталоге нет, до 100 штук по 191 символу. Приветственный экран их по-прежнему показывает

Строка берётся ровно на текущем языке интерфейса. Нет строки на этом языке — стандартный перевод («Помощники», «Поиск помощников»), без отката на другой язык ассистента. Подпись вкладки: строка из categories на текущем языке, иначе подпись вкладки или заголовок секции приветственного экрана на этом языке, иначе сам ключ. Так категориям каталога дают перевод, не переводя витрину.

Получить тексты каталога

GET /assistants/{assistantId}/templates

curl -s "$BASE/assistants/$ASSISTANT/templates" \
  -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": "Помощники" },
      "subtitle": {
        "en": "Ready-made assistants for specific tasks. Pick one — it already knows how to start the conversation.",
        "ru": "Готовые помощники под конкретные задачи. Выберите нужного — он сразу знает, с чего начать разговор."
      },
      "categories": {
        "Образ жизни": { "en": "Lifestyle" },
        "Изображения": { "en": "Images" },
        "Исследования и анализ": { "en": "Research & Analysis" }
      },
      "sidebar_label": { "en": "Assistants", "ru": "Помощники" },
      "hidden_categories": ["Создайте изображения"],
      "search_placeholder": { "en": "Search assistants", "ru": "Поиск помощников" }
    },
    "sidebar_links": null,
    "sidebar": null
  },
  "resolved": { "…": "…" }
}

Изменить тексты каталога

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

PUT /assistants/{assistantId}/templates

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь
`agents_catalog`	object или null	нет	Тело. Поля из таблицы выше. Языки — только включённые у ассистента
`sidebar`	object	нет	Тело. Тег каталога `agents_tag`, см. «Отбор по тегу»

curl -s -X PUT "$BASE/assistants/$ASSISTANT/templates" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agents_catalog": {
      "title": {"ru": "Помощники", "en": "Assistants"},
      "subtitle": {"ru": "Готовые помощники под конкретные задачи.", "en": "Ready-made assistants for specific tasks."},
      "sidebar_label": {"ru": "Помощники", "en": "Assistants"},
      "search_placeholder": {"ru": "Поиск помощников", "en": "Search assistants"},
      "categories": {
        "Изображения": {"en": "Images"},
        "Исследования и анализ": {"en": "Research & Analysis"}
      },
      "hidden_categories": ["Создайте изображения"]
    }
  }'

Ответ — {"success": true, "templates": {…}} с контейнером после записи, в той же форме, что у GET, без resolved.

Ошибка языка:

{
  "success": false,
  "error": "locale_not_active",
  "message": "Язык 'xx' не включён у проекта. Сначала добавьте его через POST /assistants/{id}/locales."
}

Пункт боковой панели ссылкой на сайт

Если каталог живёт на отдельной странице сайта, пункт «Помощники» в боковой панели можно превратить в обычную ссылку: templates.sidebar_links — «пункт → адрес», ключ agents. Адрес нормализуется так же, как page_url агента. Поле описано на странице Шаблоны и подвал.

{ "sidebar_links": { "agents": "/base/" } }

Публичный метод каталога

Данные каталога отдаёт метод фрейма без ключа — его читает сама страница каталога, им можно пользоваться и для своей витрины на сайте. Разрешён запрос с любого домена (Access-Control-Allow-Origin: *), ответ кэшируется на 5 минут.

GET https://framesuite.app/f/{frame_slug}/agents-catalog

Параметр	Тип	Обяз.	Описание
`frame_slug`	string	да	Путь. Публичный slug ассистента
`locale`	string	нет	Строка запроса. Язык текстов, синоним `lang`. Не включённый у ассистента — язык по умолчанию
`w`	string	нет	Строка запроса. Слаг приветственного экрана, с которого берутся категории. Синоним `screen`
`tag`	string	нет	Строка запроса. Служебный тег отбора. Не задан — тег каталога ассистента, если он есть

curl -s "https://framesuite.app/f/x8OA7Azs4hBy/agents-catalog?locale=en&tag=customgpt"

{
  "categories": [
    { "category": "Изображения", "label": "Images", "icon": null, "subcategories": [] },
    { "category": "Исследования и анализ", "label": "Research & Analysis", "icon": null, "subcategories": [] }
  ],
  "items": [
    {
      "id": 3678,
      "slug": "canva",
      "label": "Canva",
      "description": "Effortlessly design anything: presentations, logos, social media posts and more.",
      "author": "community builder",
      "image": "/storage/welcome-cards/canva-gpt-avatar.png",
      "image_poster": null,
      "categories": ["Изображения"],
      "page_url": "/base/canva/",
      "search_text": "what the assistant does it helps you come up with and put together visuals for any task …"
    }
  ]
}

Поле	Описание
`categories[].category`	Ключ категории — по нему вкладка и `?tab=`
`categories[].label`	Подпись на языке запроса. Может быть пустой у вкладки «только значок»
`categories[].icon`	Значок вкладки или `null`
`categories[].subcategories`	Подкатегории вкладки `[{category, label}]`, только с агентами
`items[].description`	`subtitle` или первый абзац первого сообщения
`items[].author`	`profile_author` или `null`
`items[].image`	Аватар персонажа или картинка агента. Путь `/storage/…` — от `https://framesuite.app`
`items[].categories`	Категории агента, которые есть в каталоге
`items[].page_url`	Страница агента на сайте или `null`
`items[].search_text`	Текст `page_markdown` без разметки в нижнем регистре, до 5000 символов — только для поиска. Нет описания — поля нет

Неизвестный frame_slug — 404.

Дальше

Свойства config — tags, profile_author, profile_markdown, page_url.
Первые экраны — секции и вкладки, из которых каталог берёт категории.
Сценарии — настройка каталога по шагам.