Website element markup

Site developers use data-ai-* markup to give important elements stable names, link them to instructions, and make them exact targets for highlighting or permitted actions. Start with one visitor flow and mark only the elements that help complete it.

What Markup Changes

The data-ai-* markup helps link questions like “what is this button?”, “how to fill out this field?”, “why is this tariff not available?” to a specific page element. The visitor selects an element on the site through the widget, and the widget attaches the context of the selected element to the message.

Markup describes page elements specifically. Context for the current page, open card, project, order, or another business entity is passed separately through the widget Public API: contextProvider, SenlerWidget.setPageContext(items), and one-time contextItems for the next message. By default, this context appears as chips next to the message in the widget; items with hidden: true remain hidden.

Without explicit markup, the widget still uses semantic HTML, form labels, and ARIA attributes. data-ai-* complements accessible markup with a stable key, exact name, and knowledge-base link.

Mark up your own website's elements. Buttons inside the widget already have markup: with site element actions enabled, the agent can point to a new dialog, history, and MCP connection if it is available in the channel settings. These buttons do not need your own markup or separate knowledge-base documents.

Actions run inside the widget interface or on the website page, depending on the selected target. Do not combine them in one highlight chain. The agent obtains exact keys for other website elements from context or your documentation.

Prepare the First Scenario

Connect a Widget channel and add the generated code to the site.
Enable Element selection (features.element_selection: true).
Test an ordinary button or field with a clear HTML label.
Add data-ai-* to elements that need a stable documentation or action link.

For a large site, begin with routes where users get lost most often: signup, payment, connection, search, a request form, or profile settings. Do not mark decorative containers or the entire DOM for possible future use.

Verify the Visitor Flow

The visitor clicks "Select element" in the widget.
The widget enables selection mode on the page.
The visitor clicks on a site element.
The widget reads the element name, page section, context key, and search hint if they are set.
Before sending the message, the user sees the selected element as a context chip.
The element context is sent to the agent with the question and helps retrieve the exact article.
If the user separately requests an action, the agent can address the element only by an exact key and only when the page allows that action.

Selecting an element never clicks or changes it. The visitor's click in selection mode only creates a context chip.

Mark up the scenario elements

Choose stable keys and labels using the attribute reference. For buttons, cards, forms, and custom select controls, use the markup examples. Then verify the full scenario, not just one button.

Check Markup Quality

The key is stable and does not depend on button text, interface language, or a specific user ID.
The visible article text describes the action in human language instead of repeating the context key.
The element can be found in the current page markup without navigating to another page.
A button or field has a label, role, or clear data-ai-label.
Every repeated card has the same semantic data-ai-context-id and its own complete data-ai-entity-type / data-ai-entity-id pair.
For dangerous actions such as deletion or payment, the site documentation separately explains consequences, limitations, and confirmation.

Link to knowledge base

If the site has data-ai-context-id="checkout.delivery.city", add the same key to the text of the knowledge base file:

<span data-ai-context-id="checkout.delivery.city">Enter the delivery city</span>.

When the user selects a field and asks a question, Senler AI uses context_id for knowledge base search. Documents with matching context keys receive strong priority. If the exact key is not available, data-ai-kb-query helps: it is added to the search query along with label, text and section. If the documentation is uploaded as a Markdown folder or ZIP archive, do not rely solely on visible text without markup. During upload, inline data-ai-context-id values are saved as “Context keys for elements”. File structure and key processing are covered in Linking Markdown Documentation to Website Elements.

What to Do After Markup

First link the keys to Markdown documentation, then test element selection and every allowed action. data-ai-label and data-ai-kb-query help explanations and search, but an exact action requires data-ai-context-id. If the element is absent from the current page, the action must not choose a similar target by text.

Diagnostics

If the element is not selected:

check whether "Element selection" is enabled in widget settings;
check that the user clicked “Select element” in the widget;
add data-ai-label or data-ai-context-id to the element;
do not mark only the parent container via data-ai-section if you need to select the container itself.

If the required instructions are not found:

check that data-ai-context-id matches the context key of the knowledge base file;
add data-ai-kb-query with a natural phrase;
check that the document is active and connected to the required agent;
make sure that the question is sent with the selected element block in the widget.