Формат элемента контекста

Этот формат общий для контекста страницы и контекста отдельного сообщения.

Передавайте только данные, которые разрешено видеть этому посетителю. Не добавляйте секреты, токены или платёжные данные. Контекст не выдаёт права на выполнение действий.

Опишите каждый элемент

Поле	Тип	Обязательное	Что передавать
id	string	Да	Стабильный ID элемента, например order:123.
kind	string	Да	Тип сущности: page, order, product.
role	string	Да	Назначение элемента из списка ниже.
display.label	string	Да	Короткая понятная подпись плашки.
display.subtitle	string	Нет	Дополнительное пояснение в плашке.
display.icon	string	Нет	Зарезервированный строковый идентификатор до 40 символов. Текущий интерфейс выбирает стандартную иконку по kind и не отрисовывает это значение.
display.avatar_url	string	Нет	URL изображения.
ref	object	Нет	Стабильные ID, маршрут или URL, по которым можно найти актуальный объект.
snapshot	object	Нет	Значения объекта, зафиксированные на момент отправки.
payload	object	Нет	Дополнительные JSON-данные, формат которых определяет ваша интеграция.

Значение role	Когда использовать
technical	Текущая страница или служебная часть сценария.
user_selected	Объект, который явно выбрал посетитель.
business_context	Заказ, товар, проект или другая предметная сущность вопроса.
action_target	Объект, который пользователь предполагает изменить.

Роль описывает назначение элемента, но сама по себе не выдаёт разрешение на действие. После объединения постоянного контекста, одноразового контекста и выбранного элемента в одном сообщении должно остаться не более 12 элементов.

Ограничения: id — до 120 символов, kind — до 80, display.label — до 80, display.subtitle — до 140, display.icon — до 40, display.avatar_url — до 500. ref, snapshot и payload должны быть JSON-совместимыми объектами.

Ссылки на страницу из истории

Для ссылки из плашки передавайте ref.url или ref.route. Непустой ref.url имеет приоритет. При передаче через loader относительный адрес, например /orders/123, превращается в абсолютный URL относительно страницы вашего сайта. Поэтому ссылка из сохранённой переписки ведёт к заказу на вашем сайте, а не к такому же пути внутри Senler.

При прямой передаче данных без loader указывайте полный URL с https:// или http://. Если в сохранённом контексте указан только относительный маршрут без домена, он не открывается как ссылка: по нему нельзя надёжно определить исходный сайт. Адреса с другими протоколами, включая javascript:, не становятся ссылками в истории. Сам контекст при этом остаётся доступен для чтения.

Проверьте плашки перед отправкой

Используйте ID вида page:/orders/123, project:019..., order:123. Если один объект пришёл и из page context, и из contextItems, совпадающий id оставит один тег. Разным сущностям задавайте разные kind и id, даже если подписи похожи.

Постоянный контекст, одноразовые contextItems и выбранный элемент объединяются в таком порядке и дедуплицируются по id: более поздний элемент с тем же ID заменяет предыдущий. Поэтому одноразовый элемент может уточнить постоянный, а выбранный элемент — оба предыдущих. Пользователь может удалить любую плашку из черновика до отправки.

После отправки плашки сохраняются в истории диалога только для чтения. Их можно раскрыть и, если переданы ссылки, открыть ref.url или ref.route. В деталях показывается только поддерживаемая часть данных, поэтому не рассчитывайте на отображение каждого произвольного поля payload.