Онбординг

Как это работает

Если у ассистента есть хотя бы один слайд, чат при входе показывает карусель поверх экрана. Гостю она показывается при каждом входе, пока он её не закроет; вошедшему пользователю — один раз. Пустой список — онбординга нет.

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

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

Свойство	Тип	Описание
title	string	Заголовок, до 200 знаков. Переносы строк сохраняются.
desc	string	Текст под заголовком, до 1000 знаков. Переносы строк сохраняются.
emoji	string	Эмодзи вместо картинки, до 16 знаков. Не задан и нет картинки — рисуется ✨.
image_url	string	Адрес картинки, до 500 знаков. Главнее emoji. Загрузка — POST /assistants/{assistantId}/upload/image, см. Загрузка файлов.

Методы

Получить слайды

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

GET /assistants/{assistantId}/onboarding

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

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

{
  "success": true,
  "locale": "en",
  "locales": ["ru", "en", "kk", "…"],
  "default_locale": "ru",
  "intro_slides": [
    {"title": "Hi there", "desc": "I help with orders", "emoji": "👋"},
    {"title": "Fast replies", "desc": "About a minute on average", "image_url": "https://framesuite.app/storage/welcome-cards/abc.webp"}
  ]
}

locale в ответе — запрошенный код, а не тот, чей набор реально подставился. Если для языка слайды не записаны вовсе, вернутся слайды en или базовые; если записан пустой список — "intro_slides": [].

HTTP	Когда
404	Ассистента нет или нет доступа.

Записать слайды языка

Заменяет весь набор слайдов одного языка. Другие языки не трогает. Запись для языка ассистента по умолчанию обновляет и базовый набор.

PUT /assistants/{assistantId}/onboarding

Параметр	Тип	Обяз.	Описание
assistantId	int	да	Путь.
locale	string	нет	Строка запроса или тело. Язык, чей набор пишется; если задан в обоих местах, главнее строка запроса. Без обоих — язык ассистента по умолчанию. Должен быть в языках ассистента.
intro_slides	array	да	Тело. До 10 слайдов. Поле обязано быть в теле; [] или null выключает онбординг на этом языке.
strict	bool	нет	Тело или строка запроса. true — незнакомые поля дают 422 вместо предупреждения.

curl -s -X PUT "$BASE/assistants/$ASSISTANT/onboarding?locale=ru" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intro_slides": [
      {"title": "Здравствуйте", "desc": "Я помогу с заказами", "emoji": "👋"},
      {"title": "Отвечаю быстро", "desc": "В среднем за минуту", "image_url": "https://framesuite.app/storage/welcome-cards/abc.webp"}
    ]
  }'

{
  "success": true,
  "applied": ["intro_slides_locales", "intro_slides"],
  "ignored": [],
  "locale": "ru"
}

applied — что реально записано (intro_slides появляется, только если писали язык по умолчанию), ignored — незнакомые поля тела; при них в ответе ещё warning.

Без поля intro_slides (пустое тело, опечатка в имени) метод отвечает 422 и слайды не трогает. Выключить онбординг на языке можно только явно: "intro_slides": [] или null. Пустой список хранится как настройка языка, и посетитель на этом языке онбординг не увидит — ни свой, ни английский.

HTTP	Когда
404	Ассистента нет или нет доступа.
422	Язык не включён у ассистента: {"success": false, "error": "locale_not_active", "message": "Locale 'xx' is not in project.locales. Add it via POST /assistants/53/locales first."}.
422	В теле нет intro_slides: {"success": false, "errors": {"intro_slides": ["The intro slides field must be present."]}}.
422	Ошибка проверки: {"success": false, "errors": {"intro_slides.0.emoji": ["The intro_slides.0.emoji field must not be greater than 16 characters."]}}.
422	strict=true и есть незнакомые поля: {"success": false, "error": "unknown_fields", "ignored": ["…"]}.

Дальше

• Первые экраны — что посетитель видит после онбординга.
• Языки и переводы — как включить язык, чтобы писать для него слайды.
• Загрузка файлов — картинки для слайдов.