Element selection, highlighting, and website actions

What the Visitor Experiences

A visitor can select a button, field, card, or another element on your website through the widget and send a question about that exact element. Its name and markup are sent with the question, so the AI assistant can explain the element, find a linked instruction, highlight it, scroll to it, or perform a permitted action.

Enable Element Selection

In Dynamic mode, enable Page element selection in the channel settings and save the changes. In Static mode, set features.element_selection: true, then copy the updated code to the site. Markers 1–4 in the screenshot identify the independent file upload, voice message, emoji, and split-view features; the Page element selection switch required here is marked 5.

How a Visitor Selects an Element

The visitor clicks “Select element” in the widget input area.
Selection mode starts on the page and highlights the available element under the pointer.
The visitor clicks the required element. Its normal action is not performed at this point.
A selected-element chip appears above the input. The visitor can reveal the element on the page again or remove the chip before sending the question.
After a successful send, the selected element is attached only to that message and is cleared. After an error, it remains in the draft so the visitor can retry.

The Escape key cancels selection mode. The website sends current page context separately through the Widget Public API; a selected element does not replace it.

Check the Transmitted Data

Selected-element context contains only information extracted by the widget from the page:

page URL and title;
visible text or data-ai-label;
page area and section;
element type, HTML role, and declared action meaning;
stable data-ai-context-id;
data-ai-kb-query search hint;
business entity type and ID for repeated cards or rows.

For repeated elements, provide data-ai-entity-type and data-ai-entity-id as a pair. The agent can then distinguish a specific product, order, or list row. If several elements have the same context key and cannot be distinguished, no automatic action is performed.

Technically, the data is grouped into element (label, role, tag, kind, action, and visible text), place (URL, title, area, and section), ref (context key, document reference, search phrase, and entity), and state (disabled, selected, and invalid flags). The loader does not read a field's JavaScript value property and does not send an entered password. However, visible text and data-ai-*, aria-*, title, and placeholder values used to describe the element may be included in context, so do not put secrets in them.

Page and business-object context is supplied separately. Selecting a button does not by itself add a lead, order, or project ID to selected-element context. System lead fields may still be available to the agent from the lead profile; add site data through widget context or markup for the specific entity.

Prepare a Stable Target

An important element usually needs:

data-ai-context-id — a stable key for documentation links and actions;
data-ai-label — a human-readable name;
data-ai-kb-query — a search phrase for cases where the knowledge base has no exact key.

Example:

<button
  data-ai-context-id="checkout.payment.submit"
  data-ai-label="Pay for order"
  data-ai-kind="primary-action"
  data-ai-action="checkout.payment.submit"
  data-ai-kb-query="how to pay for an order"
>
  Pay
</button>

data-ai-section only describes a section and does not make a container selectable by itself. The full attribute list, length limits, and rules for repeated elements are in Website element markup.

data-ai-action describes the meaning of a button; it does not authorize execution. For clicking, filling, and other changes, the site must keep the same authentication, restrictions, and confirmations used for normal visitor actions.

Describe the Path to a Hidden Target

In documentation, name the final target, for example: “Open notification settings.” If the target is hidden in a menu or panel, the agent needs a way to find the element that reveals it.

Standard aria-controls, popovertarget, commandfor, and <details>/<summary> relationships are detected automatically. For a custom component, declare the revealed context root explicitly:

<button
  data-ai-context-id="account.menu.toggle"
  data-ai-label="Open account menu"
  data-ai-reveals-context-id="account.notifications"
  data-ai-reveal-action="click"
>
  Menu
</button>

<a
  data-ai-context-id="account.notifications.open"
  data-ai-label="Notification settings"
  href="/account/notifications"
>
  Notifications
</a>

data-ai-reveal-action accepts click, hover, or focus; click is used when the attribute is omitted. One trigger can reveal several roots separated by spaces. A nested interface may use up to 8 reveal operations.

For click, focus, fill, clear, select, and toggle, the widget can perform the discovered reveal steps and then address the final target. For highlight and scroll_to, hidden panels are not opened automatically: the visitor is shown the available trigger and the path continues after it is opened.

Link the Target to a Guide

Wrap a human-readable Markdown phrase in the same data-ai-context-id used by the website element:

Click the <span data-ai-context-id="checkout.payment.submit">payment button</span>
to proceed with the order payment.

When Markdown is imported, the key is stored in document metadata. When a visitor selects the marked element, search gets an exact link to the relevant instruction. data-ai-kb-query remains a text fallback.

For details on importing these keys, see Linking Markdown documentation to website elements.

Actions and Limits

After an explicit user request, the agent can call one of eight types:

Type	Result	Limit
`highlight`	Highlights the target.	Does not open a hidden panel automatically.
`scroll_to`	Scrolls to the target.	Does not open a hidden panel automatically.
`focus`	Moves focus to an element.	The target must support focus.
`click`	Clicks a button, link, or another available HTMLElement.	Disabled targets are blocked; the site must confirm dangerous consequences.
`fill`	Fills a text-like `input`, `textarea`, or `contenteditable`.	Password, card, and other sensitive fields are blocked.
`clear`	Clears an `input`, `textarea`, `select`, or `contenteditable`.	The target must support clearing.
`select`	Selects an option in an HTML `select` or a custom control with combobox/listbox markup.	The option must be unambiguous and available. An arbitrary button without the select contract is not supported.
`toggle`	Changes a checkbox, radio, or `role="switch"` element.	It does not apply to arbitrary buttons.

An action uses an exact data-ai-context-id, not fuzzy label matching. Supply either one target or a chain of up to 12 targets, never both. A chain supports only highlight and scroll_to: the widget finds the furthest available step and continues the guide after a DOM change or visitor click.

When the same key occurs more than once, the target needs a complete entity_type and entity_id pair. Otherwise, the ambiguous action is blocked.

If no exact element is found or several elements match equally, the agent does not choose one at random and explains the route in words.

How to Read the Result

While an action runs, the widget shows a card with its target, state, and execution details.

Final states:

completed — the page confirmed execution;
not found — the element is not on the current screen;
blocked — the action cannot be performed automatically;
error — the action failed.

The interface may show an intermediate execution state, but only success, not_found, blocked, and failed are final results. Do not treat the action as complete until the card shows success.

Diagnostics

If element selection or an action does not work:

Check that “Element selection” is enabled in widget settings.
Make sure the page loads the current widget code.
Check that the element has readable text, data-ai-label, or data-ai-context-id.
Do not reuse one data-ai-context-id for several elements without a data-ai-entity-type / data-ai-entity-id pair.
For a hidden target, check its standard trigger relationship or data-ai-reveals-context-id.
To find an instruction, check that the key matches in the element and Markdown; add data-ai-kb-query if necessary.
For a “not found” state, make sure the user is on the right page and the element has already rendered.

What to Add Next

Markup on this page is enough for ordinary highlighting and DOM actions. If an agent response must run a separate site business operation, such as opening an order through your router or preparing payment, use a custom action. To edit field text with a review step before application, use inline edits.