Выбор элемента, подсветка и действия на сайте

Что происходит для посетителя

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

Включите выбор элементов

В динамическом режиме включите в настройках канала функцию «Выбор элемента страницы» и сохраните изменения. В статичном режиме задайте features.element_selection: true, затем скопируйте обновлённый код на сайт. На снимке цифрами 1–4 отмечены независимые функции загрузки файлов, голосовых сообщений, эмодзи и разделённого окна; нужный для этого сценария переключатель «Выбор элемента страницы» отмечен цифрой 5.

Как посетитель выбирает элемент

Посетитель нажимает «Выбрать элемент» в поле ввода виджета.
На странице включается режим выбора: под курсором подсвечивается доступный элемент.
Посетитель нажимает на нужный элемент. Обычное действие элемента в этот момент не выполняется.
Над полем ввода появляется плашка с выбранным элементом. Её можно показать на странице повторно или удалить до отправки вопроса.
После успешной отправки выбранный элемент прикладывается только к этому сообщению и очищается. При ошибке он остаётся в черновике для повторной попытки.

Клавиша Escape отменяет режим выбора. Контекст текущей страницы сайт передаёт отдельно через Public API виджета; выбранный элемент его не заменяет.

Проверьте передаваемые данные

Контекст выбранного элемента содержит только сведения, которые виджет извлёк из страницы:

URL и заголовок страницы;
видимый текст или data-ai-label;
область и раздел страницы;
тип элемента, роль HTML и описанный смысл действия;
стабильный data-ai-context-id;
поисковая подсказка data-ai-kb-query;
тип и ID бизнес-сущности для повторяющихся карточек или строк.

Для повторяющихся элементов задавайте data-ai-entity-type и data-ai-entity-id парой. Тогда агент отличит конкретный товар, заказ или строку списка. Если несколько элементов имеют одинаковый контекстный ключ и различить их нельзя, автоматическое действие не выполняется.

Технически сведения распределены по element (название, роль, тег, тип, действие и видимый текст), place (URL, заголовок, область и раздел), ref (контекстный ключ, ссылка на документ, поисковая фраза и сущность) и state (признаки disabled, selected и invalid). Скрипт-загрузчик не читает JavaScript-свойство value у поля и не передаёт введённый пароль. При этом видимый текст и значения data-ai-*, aria-*, title и placeholder, использованные для описания элемента, могут попасть в контекст — не помещайте в них секретные данные.

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

Подготовьте стабильную цель

Для важного элемента обычно достаточно:

data-ai-context-id — стабильный ключ для связи с документацией и действиями;
data-ai-label — понятное человеку название;
data-ai-kb-query — поисковая фраза на случай, если точного ключа нет в базе знаний.

Пример:

<button
  data-ai-context-id="checkout.payment.submit"
  data-ai-label="Оплатить заказ"
  data-ai-kind="primary-action"
  data-ai-action="checkout.payment.submit"
  data-ai-kb-query="как оплатить заказ"
>
  Оплатить
</button>

data-ai-section сам по себе только описывает раздел и не делает контейнер выбираемым. Полный список атрибутов, ограничения длины и правила для повторяющихся элементов приведены в статье «Разметка элементов сайта».

data-ai-action описывает смысл кнопки, но не разрешает выполнение. Для клика, заполнения и других изменений сайт всё равно должен сохранять авторизацию, ограничения и подтверждения, которые действуют при обычной работе пользователя.

Опишите путь к скрытой цели

В документации указывайте конечную цель, например: «Откройте настройки уведомлений». Если цель скрыта в меню или панели, агенту нужен способ найти элемент, который её раскрывает.

Стандартные связи aria-controls, popovertarget, commandfor и <details>/<summary> определяются автоматически. Для собственного компонента явно укажите корень раскрываемого контекста:

<button
  data-ai-context-id="account.menu.toggle"
  data-ai-label="Открыть меню аккаунта"
  data-ai-reveals-context-id="account.notifications"
  data-ai-reveal-action="click"
>
  Меню
</button>

<a
  data-ai-context-id="account.notifications.open"
  data-ai-label="Настройки уведомлений"
  href="/account/notifications"
>
  Уведомления
</a>

data-ai-reveal-action принимает click, hover или focus; без атрибута используется click. Один переключатель может раскрывать несколько корней — перечислите их через пробел. Во вложенном интерфейсе может быть до 8 операций раскрытия.

Для click, focus, fill, clear, select и toggle виджет может последовательно выполнить найденное раскрытие и затем действие с конечной целью. Для highlight и scroll_to скрытые панели автоматически не открываются: посетителю показывается доступный переключатель, после его открытия путь продолжается.

Свяжите цель с инструкцией

Оберните человекочитаемую фразу в Markdown тем же data-ai-context-id, который задан элементу сайта:

Нажмите <span data-ai-context-id="checkout.payment.submit">кнопку оплаты</span>,
чтобы перейти к оплате заказа.

При импорте Markdown ключ сохраняется в метаданных документа. Когда посетитель выбирает размеченный элемент, поиск получает точную связь с соответствующей инструкцией. data-ai-kb-query остаётся текстовым запасным вариантом.

Подробнее об импорте таких ключей: «Связь Markdown-документации с элементами сайта».

Действия и ограничения

После явного запроса пользователя агент может вызвать один из восьми типов:

Тип	Результат	Ограничение
`highlight`	Подсвечивает цель.	Не открывает скрытую панель автоматически.
`scroll_to`	Прокручивает страницу к цели.	Не открывает скрытую панель автоматически.
`focus`	Переводит фокус на элемент.	Цель должна поддерживать фокус.
`click`	Нажимает кнопку, ссылку или другой доступный HTMLElement.	Отключённый элемент блокируется; опасные последствия должен подтверждать сам сайт.
`fill`	Заполняет текстовый `input`, `textarea` или `contenteditable`.	Парольные, карточные и другие чувствительные поля блокируются.
`clear`	Очищает `input`, `textarea`, `select` или `contenteditable`.	Цель должна поддерживать очистку.
`select`	Выбирает вариант в HTML `select` или нестандартном списке с разметкой combobox/listbox.	Вариант должен быть однозначным и доступным. Произвольная кнопка без контракта списка не поддерживается.
`toggle`	Меняет checkbox, radio или элемент с `role="switch"`.	Не применяется к произвольным кнопкам.

Действие использует точный data-ai-context-id, а не нечёткий поиск по подписи. Можно передать одну цель либо цепочку до 12 целей, но не оба варианта одновременно. Цепочка поддерживает только highlight и scroll_to: виджет находит самый дальний доступный шаг и продолжает подсказку после изменения DOM или клика пользователя.

Если одинаковый ключ встречается несколько раз, у цели должна быть полная пара entity_type и entity_id. Без неё неоднозначное действие блокируется.

Если точный элемент не найден или несколько элементов подходят одинаково, агент не выбирает случайный вариант и объясняет путь словами.

Как понять результат

Во время действия виджет показывает карточку с целью, состоянием и деталями выполнения.

Итоговые состояния:

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

Во время выполнения интерфейс может показывать промежуточное состояние, но результатом считаются только success, not_found, blocked или failed. Не считайте действие выполненным, пока карточка не показывает успешное состояние.

Диагностика

Если выбор элемента или действие не работает:

Проверьте, включён ли «Выбор элемента» в настройках виджета.
Убедитесь, что на странице загружен актуальный код виджета.
Проверьте, что у элемента есть понятный текст, data-ai-label или data-ai-context-id.
Не используйте один data-ai-context-id для нескольких элементов без пары data-ai-entity-type / data-ai-entity-id.
Для скрытой цели проверьте стандартную связь с переключателем или data-ai-reveals-context-id.
Для поиска инструкции проверьте совпадение ключа в элементе и Markdown; при необходимости добавьте data-ai-kb-query.
При состоянии «не найдено» убедитесь, что пользователь находится на нужной странице и элемент уже отрисован.

Что подключать дальше

Для обычной подсветки и работы с DOM достаточно разметки этой страницы. Если ответ агента должен запускать самостоятельную бизнес-операцию сайта, например открыть заказ через маршрутизатор сайта или подготовить оплату, используйте custom action. Для редактирования текста в поле с просмотром результата до применения используйте inline-правки.