Как устроена интеграция виджета

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

Три части интеграции

• Контекст сообщает агенту, где находится посетитель и о каком объекте идёт речь. Например: «Открыт раздел оплаты» или «Открыт заказ № 123».
• Разметка даёт важным элементам страницы стабильные ключи и связывает их с фразами в документации.
• Действия позволяют виджету попросить страницу подсветить элемент, прокрутить к нему, изменить поле или выполнить отдельный обработчик сайта.

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

Какие данные используются при подготовке ответа

При подготовке ответа могут использоваться профиль лида, инструкция агента и контекст, который сайт явно передал виджету. Произвольное JavaScript-состояние страницы автоматически не читается.

Если агенту нужны номер заказа, название товара или другой параметр открытой сущности, добавьте его в контекст страницы или сообщения. Системные поля лида, которые можно вставить в инструкцию агента, перечислены в статье «Данные и переменные в агенте».

Как выглядит полная связка

Предположим, на сайте есть кнопка оплаты:

1. Сайт передаёт контекст: посетитель находится на странице оформления заказа, открыт заказ № 123.
2. Кнопка получает стабильный ключ checkout.payment.submit по инструкции «Разметка элементов сайта».
3. Тот же ключ обрамляет обычную фразу в Markdown-инструкции: «Нажмите кнопку оплаты».
4. Посетитель выбирает кнопку и задаёт вопрос. Виджет передаёт выбранный элемент вместе с сообщением.
5. Агент находит связанную инструкцию и объясняет действие. Если сайт поддерживает нужный сценарий, виджет может показать элемент или выполнить разрешённое действие.

Сначала соберите один простой сценарий: одна страница, один элемент и одна связанная фраза. После проверки добавляйте остальные элементы, custom actions, inline-правки и методы Public API.

Безопасность и ответственность сайта

В браузер можно передавать URL скрипта-загрузчика, channel_id, настройки интерфейса, данные посетителя и уже вычисленный user_hash. Секрет канала, из которого создаётся подпись, и проектные API-ключи должны оставаться на сервере сайта.

Контекст сообщения, видимый текст элемента и значения data-ai-* передаются Senler AI. Не помещайте в них пароли, токены, платёжные реквизиты и другие секреты.

Данные payload, полученные обработчиком customActions, считайте недоверенными. Сайт должен заново проверить их типы, пользователя, права и допустимость операции. Подтверждение оплаты, удаления и других значимых действий остаётся частью интерфейса и серверной логики сайта.

Что проверять после изменений сайта

Если кнопку, поле или меню перенесли либо переименовали, проверьте вместе разметку элемента, связанную фразу в документации и сценарий действия. Стабильный data-ai-context-id меняйте только тогда, когда изменился смысл элемента, а не его подпись или положение на странице.