Контекст страницы и сообщения виджета

Контекст — это явные данные, которые сайт прикладывает к сообщению, чтобы агент понимал текущую ситуацию. Например: «Открыт раздел оплаты» или «Пользователь спрашивает о заказе № 123». Начните с одной плашки страницы и добавляйте бизнес-сущности только там, где они действительно нужны.

Что получает агент

Агент получает элементы контекста целиком: их тип, роль, понятную подпись и переданные объекты ref, snapshot и payload. Посетитель видит подписи как плашки над полем ввода и рядом с отправленным сообщением.

Контекст не читает произвольное состояние страницы. Системные данные текущего лида Senler передаёт отдельно из его профиля; заказ, проект и другие данные сайта нужно явно добавить в контекст. Не добавляйте секреты, токены, платёжные данные и сведения, которые этот посетитель не должен видеть. Если инструкции агента нужен точный ID или профильное поле лида, используйте системные переменные лида, а не дублируйте эти значения в каждом contextItems.

Выберите вид контекста

• Постоянный контекст страницы задаётся через contextProvider при SenlerWidget.init и заменяется через SenlerWidget.setPageContext(items) при навигации.
• Одноразовый контекст сообщения передаётся как contextItems в SenlerWidget.open({ contextItems, message }) или SenlerWidget.updateRuntime({ contextItems, message }).

Постоянный контекст подходит для текущего экрана и будет предлагаться со следующими сообщениями. Одноразовый подходит для конкретного заказа, рекомендации или цели текущего вопроса и удаляется из черновика после успешной отправки. При ошибке отправки он сохраняется, чтобы пользователь мог повторить попытку.

Передайте текущую страницу

contextProvider вызывается один раз при инициализации и должен сразу вернуть готовый массив: асинхронный Promise не поддерживается. Если название страницы или сущность загружается позже, сначала верните базовый элемент контекста, а после загрузки вызовите SenlerWidget.setPageContext(items).

Если вместо функции передать другое значение, init завершится синхронной ошибкой. Если сама функция выбросит исключение или вернёт некорректный массив, скрипт-загрузчик выведет предупреждение [SenlerWidget] contextProvider callback failed в консоль и продолжит запуск без этого контекста. Поэтому отдельно проверьте плашку страницы в готовом виджете.

function buildPageContext() {
  return [
    {
      id: `page:${window.location.pathname}`,
      kind: "page",
      role: "technical",
      display: {
        label: document.title || "Текущая страница",
        subtitle: window.location.pathname,
      },
      ref: {
        url: window.location.href,
        route: window.location.pathname,
      },
    },
  ];
}

SenlerWidget.init({
  channel_id: "xxx",
  contextProvider: buildPageContext,
});

В SPA после каждой смены маршрута заменяйте контекст без переинициализации:

SenlerWidget.setPageContext(buildPageContext());

setPageContext(items) заменяет весь постоянный контекст, а не дополняет предыдущий массив. Передавайте в него полный актуальный набор. Чтобы убрать постоянный контекст, вызовите SenlerWidget.setPageContext([]).

Добавьте объект текущего вопроса

Передайте contextItems, когда открываете чат для конкретной сущности или действия:

SenlerWidget.open({
  contextItems: [
    {
      id: "order:123",
      kind: "order",
      role: "business_context",
      display: {
        label: "Заказ #123",
        subtitle: "Открытая карточка",
      },
      ref: {
        entity_type: "order",
        entity_id: "123",
        route: "/orders/123",
      },
      snapshot: {
        status: "awaiting_payment",
        total: "4 900 ₽",
      },
      payload: {
        available_actions: ["pay", "cancel"],
      },
    },
  ],
  message: {
    text: "Опиши, что можно сделать с этим заказом.",
    startNewDialog: true,
    autoSend: true,
  },
});

В примере посетитель видит плашку «Заказ #123», а агент получает ID, маршрут, состояние заказа и доступные действия вместе с вопросом. Это данные для ответа, а не разрешение выполнить оплату или отмену. Одноразовый контекст очищается только после успешной отправки. Постоянный контекст страницы остаётся для следующих сообщений.

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

Поле	Тип	Обязательное	Что передавать
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-совместимыми объектами.

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

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

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

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

Контекст выбранного элемента

Элемент, выбранный через функцию features.element_selection, добавляется как обычный элемент контекста с типом selected_element. Отдельно передавать его в contextItems не нужно.

Чтобы контекст содержал понятное название, назначение и связь с документацией, добавьте элементам страницы data-ai-* атрибуты. Подробности — в «Разметке элементов сайта» и «Подсветке и действиях».

Когда обновлять контекст

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

Что настраивать дальше

Когда плашки страницы и бизнес-сущности передаются корректно, добавьте важным кнопкам, полям и карточкам стабильную разметку data-ai-*. Контекст объясняет агенту ситуацию, а разметка позволяет связать ответ с конкретным элементом сайта.