Контекст страницы

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

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

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

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

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

• Контекст страницы для интерфейса чата задаётся через contextProvider при SenlerWidget.init и заменяется через SenlerWidget.setPageContext(items) при навигации. Он предлагается со следующими сообщениями, которые посетитель отправляет из поля ввода.
• Контекст программного запроса передаётся явно как contextItems в SenlerWidget.ask({ text, contextItems }). Этот вызов не подхватывает плашки из setPageContext, контекст черновика или выбранный в интерфейсе элемент.
• Общий JSON-контекст для ask задаётся через setContext; параметр context дополняет или переопределяет его для одного запроса.

Если посетитель должен сам написать вопрос об объекте, передайте одноразовые contextItems в selectDialog или startNewDialog. Они появятся в поле ввода и перейдут в сообщение при отправке. Если отправка не удалась, кнопка «Повторить» у сообщения использует тот же контекст; прикреплять его заново не нужно.

Пример для конкретного заказа находится в контексте сообщения; все поля, лимиты и правила объединения описаны в формате элемента контекста.

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

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([]).

Для программного вопроса о той же странице передайте актуальный массив непосредственно в ask:

await SenlerWidget.ask({
  text: "Помоги разобраться с текущей страницей.",
  contextItems: buildPageContext(),
});

Контекст в виде JSON

Если для интеграции достаточно одного объекта без отдельных плашек сущностей, используйте SenlerWidget.setContext(context):

SenlerWidget.setContext({ section: "orders", orderId: "123" });
const result = await SenlerWidget.ask({
  text: "Объясни состояние заказа.",
  context: { orderId: "456" },
});

В этом запросе сохраняется section: "orders", а orderId заменяется на "456". Объекты объединяются только на верхнем уровне: вложенный объект из запроса заменяет соответствующий объект целиком. Параметр context у ask не меняет постоянное значение.

Каждый вызов ask сохраняет собственный снимок данных до ожидания в очереди. Последующий переход на другую страницу не изменяет уже отправленный запрос. Допускается JSON-объект размером до 16 000 байт и вложенностью до 8 уровней; функции, циклические ссылки и небезопасные имена ключей не принимаются.

setContext также заменяет плашки постоянного контекста в интерфейсе чата одной плашкой «Context». Выберите один способ управления постоянным контекстом: последующий setPageContext меняет плашки интерфейса, но не очищает JSON, сохранённый для ask. Для нескольких плашек, собственных подписей и флага hidden используйте setPageContext для ручной отправки и явно передавайте contextItems в ask. Вызов setContext({}) очищает сохранённый JSON и постоянные плашки.

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

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

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

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