Экран-профиль агента и ссылки на агента в API bota.chat

Что такое экран-профиль

Экран-профиль — первый экран агента в стиле кастомного GPT: по центру аватар, название, строка «От …», короткое описание и до четырёх карточек-вариантов, внизу обычное поле ввода. Человек сначала видит, что это за агент, и начинает диалог вариантом или своим сообщением.

Своих полей у профиля почти нет — он собирается из полей агента:

Что на экране	Откуда берётся
Аватар	`character_avatar`, иначе `image_poster`, иначе `image` (если это не видео). Нет ни одного — пастельная заглушка
Название	`label`
«От …»	`profile_author`. Пусто — строки нет. Ссылка автора `profile_author_url` хранится, но пока не выводится
Описание	`subtitle`
Карточки-варианты	Первые четыре `text` из `prepared_suggestions`
Поле ввода	Обычное поле чата ассистента

Все тексты берутся на языке интерфейса посетителя из locales. Документ страницы агента на сайте page_markdown (раньше назывался profile_markdown) на профиле не выводится: это страница для OnPress, которую публикуют на сайт, а в чате он участвует только в поиске каталога. Подробно — Свойства config.

Профиль работает у агентов с action send, image и document без frame_id. У send выбор варианта или своё сообщение начинают диалог: сначала скрыто уходит промпт агента, потом реплика человека. Заготовленное первое сообщение (prepared_response) при этом не показывается — его роль играет профиль. У image и document действие из профиля открывает их обычный сценарий: загрузку фото, лендинг, пейволл. Персонажи и агенты с фреймом всегда открываются по-старому.

Где агент открывается профилем

Режим — свойство не агента целиком, а пары «вход — агент». Один и тот же агент на одном приветственном экране открывается диалогом, на другом — профилем.

Настройка	Где	Что делает
`profile_screens`	`config` агента	Слаги приветственных экранов, на которых клик по карточке и ссылка на агента открывают профиль. Слаги экранов — в `GET /assistants/{assistantId}/welcome-screens`, см. Первые экраны. Существование экрана не проверяется. Пробелы по краям и повторы убираются, и плоско, и внутри `config`; пустая строка в массиве — 422. Массив заменяется целиком, `null` снимает список. При копировании агента в другого ассистента дашборд оставляет только слаги экранов приёмника
`agent_view=profile`	Параметр ссылки	Профиль независимо от `profile_screens`
`agent_view=chat`	Параметр ссылки	Сразу диалог, даже если экран в `profile_screens`

Карточки каталога «Помощники» всегда ведут на профиль (или на страницу агента на сайте, если задан page_url), поэтому для каталога profile_screens заполнять не нужно.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/agents/3676" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subtitle": "Поиск и разбор научных статей",
    "profile_author": "awesomegpts.ai",
    "profile_author_url": "https://awesomegpts.ai/",
    "profile_screens": ["LQmAMDZFO44o"],
    "prepared_suggestions": [
      {"text": "Найди свежие исследования про ИИ"},
      {"text": "Разбери статью по ссылке"}
    ],
    "locales": {"en": {"subtitle": "Find and read research papers", "profile_author": "awesomegpts.ai"}}
  }'

Ссылка на агента

Агента открывает параметр agent в адресе чата ассистента. Значение — slug агента, его числовой id или название, приведённое к slug (Scholar GPT → scholar-gpt). Агент должен принадлежать этому ассистенту: чужой или несуществующий молча игнорируется, и открывается обычный приветственный экран.

https://framesuite.app/f/{frame_slug}?agent=scholar-gpt
https://framesuite.app/f/{frame_slug}?agent=scholar-gpt&agent_view=profile
https://framesuite.app/f/{frame_slug}?agent=3676&agent_view=chat
https://ваш-домен.ru/?agent=scholar-gpt&agent_view=profile

frame_slug ассистента отдают GET /assistants/{assistantId}/links и методы встраивания, см. Домены, Telegram, встраивание.

Параметры адреса чата, связанные с агентами:

Параметр	Значение	Что делает
`agent`	slug, id или название агента	Открыть агента: диалогом или профилем
`agent_view`	`profile` или `chat`	Режим первого экрана агента, главнее `profile_screens`
`w`	слаг экрана	Какой приветственный экран открыть. От экрана зависит `profile_screens`
`screen`	слаг экрана	То же, что `w`, для сайтов на WordPress: там `w` занят ядром
`lib`	`agents`	Открыть каталог «Помощники», см. Каталог
`tab`	ключ категории	Вкладка каталога при `lib=agents`
`tag`	служебный тег	Показать в каталоге только агентов с этим тегом
`a`	slug из `/links`	Открывает агента так же, как клик по его карточке на приветственном экране: `image` и `document` — своим экраном, агента-сообщение — диалогом или профилем, если он включён для входа. Работает только для агентов с карточкой на этом экране; для любого агента — `agent`
`r`	код партнёра	Партнёрская ссылка, совместима с `agent`

Ссылка с agent всегда начинает новый диалог, даже если у посетителя уже был чат с ассистентом. После запуска параметр снимается с адреса, поэтому перезагрузка страницы не запускает агента второй раз.

Готовая ссылка на профиль собирается так же на своём домене ассистента и при встраивании в сайт: к адресу страницы, где открыт чат, добавляются ?agent=<slug>&agent_view=profile.

Список ссылок на агентов

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

GET /assistants/{assistantId}/links

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	Путь
`action`	string	нет	Строка запроса. Фильтр по `action`, несколько через запятую: `send,image`
`section`	string	нет	Строка запроса. Номер секции с 0 или часть её заголовка
`q`	string	нет	Строка запроса. Поиск по названию
`prefer`	string	нет	Строка запроса. `web` или `telegram` — добавить в каждую запись поле `url` нужного вида

curl -s "$BASE/assistants/$ASSISTANT/links?action=send&prefer=web" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "frame_slug": "x8OA7Azs4hBy",
  "tg_bot_username": "bota_chat_bot",
  "tg_bot_app_name": "app",
  "count": 9,
  "links": [
    {
      "slug": "perevesti",
      "label": "Перевести",
      "action": "send",
      "icon": "zap",
      "emoji": null,
      "image": null,
      "image_poster": null,
      "prompt": "Ты — помощник-переводчик. …",
      "section_index": 0,
      "section_title": null,
      "web_url": "https://bota.chat/?a=perevesti",
      "telegram_url": "https://t.me/bota_chat_bot/app?startapp=perevesti",
      "url": "https://bota.chat/?a=perevesti"
    }
  ]
}

GET /assistants/{assistantId}/links/{slug} отдаёт одну запись в поле link, если slug нет — 404 {"success": false, "error": "Link not found"}.

web_url строится от своего домена ассистента, если он подключён (https://bota.chat/?a=perevesti), иначе — https://framesuite.app/f/<frame_slug>?a=<slug>. web_url и telegram_url (?startapp=<slug>) открывают агента как клик по карточке: агента-картинку и агента-документ — своим экраном, агента-сообщение — диалогом или экраном-профилем, если он включён для входа. Прошлый диалог при этом не восстанавливается.

slug ссылок — не slug агента

Метод /links строит свой slug из названия агента, и в него попадают только агенты секций приветственного экрана по умолчанию: ссылка на агента без карточки на экране ничего не открывает. Для ссылки на любого агента берите slug из списка агентов и параметр ?agent=.

Дальше

Свойства config — profile_screens, profile_author, profile_author_url, page_url, page_markdown.
Каталог «Помощники» — страница со всеми агентами по категориям.
Сценарии — агент с экраном-профилем и страницей на сайте.