Website Element Markup

In short

Mark only the elements users may actually ask about: buttons, fields, cards, menu items, form steps, and important states. You do not need to cover every decorative container.

A good minimum set for an element is data-ai-context-id for a stable link, data-ai-label for a clear name, and data-ai-kb-query as a search fallback. For repeated cards, use a shared context_id and separate data-ai-entity-type / data-ai-entity-id.

For repeated rows and cards, always provide data-ai-entity-type and data-ai-entity-id as a pair. The shared data-ai-context-id describes the kind of element, such as a lead row, while the entity pair identifies one specific lead. When several elements with the same context key are visible, an action without this pair is ambiguous and is not performed; providing only one of the two attributes is also invalid.

What does markup provide?

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. In the dialog, all of this appears as context chips next to the message.

The same markup is used by the quick "Ask AI" action for a visible element. If the element has a clear data-ai-label, the user can ask about it; if it also has a stable data-ai-context-id, the question links more reliably to the exact article, the right place to highlight, or an allowed page action.

Without markup, the widget also tries to collect context from regular HTML: text, aria-label, label, placeholder, nearby aside, nav, main, header, footer, form, dialog, table. But data-ai-* gives stable keys and better links the question to the knowledge base.

How to enable

Connect the Widget channel and paste the widget code onto the site.
In the widget settings, enable the “Element selection” function (features.element_selection: true).
Add data-ai-* attributes to important site elements.
In the Markdown documentation, wrap the phrase that describes the element in span data-ai-context-id with the same key.

If the site is large, do not start with every page at once. Start with routes where users get lost most often: signup, payment, connection, search, request form, profile settings.

How this works in practice

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.
This chip points to a more precise article and an answer about the selected place.
If the user asks for an action, the element can be highlighted, scrolled to, clicked, or filled only when this is allowed and the element is found on the current screen.
If there is no exact link, the route is explained in words.

Which elements can be selected

These are considered selectable:

elements with data-ai-context-id, data-ai-label, data-ai-kind, data-ai-action, data-ai-kb-doc-id, data-ai-kb-query;
standard elements button, a, input, textarea, select, label, summary;
text and structural elements article, section, li, p, h1-h6;
elements with roles button, link, menuitem, tab, checkbox, radio, option;
elements with aria-label or aria-labelledby.

data-ai-section by itself only describes the section. If you need to select the entire block, add data-ai-label, data-ai-kind or data-ai-context-id to it.

Attributes

data-ai-area - large area of the page: header, navigation, sidebar, content, main, form, modal, footer.
data-ai-section - semantic section: catalog, checkout-payment, pricing, profile-settings.
data-ai-label - human-readable name of the element.
data-ai-kind - element type: primary-action, form-field, product-card, plan-card, menu-item, status-badge.
data-ai-action - semantic action: cart.add, checkout.pay, plan.choose, support.open.
data-ai-context-id - stable key for connecting to the knowledge base. For the client's site, use lowercase slug separated by dots, for example checkout.payment.submit; for the Senler AI cabinet, the cabinet.<section>.<screen>.<element> format is used, for iframe dialogs - dialog.<section>.<screen>.<element>.
data-ai-kb-doc-id - direct ID of the knowledge base document, if it is known and stable. For Senler AI downloadable MD documentation, do not use it as your primary connection.
data-ai-kb-query - search hint for the knowledge base, for example “how to pay for an order”.
data-ai-entity-type - business entity type: product, plan, order, article.
data-ai-entity-id - business entity ID, for example SKU or public tariff ID.

Do not put passwords, tokens, email, phone, personal data, or secret service IDs in attributes.

Quality mini-checklist

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.
Dangerous actions such as deletion or payment have a separate article with limitations.

Real scenarios

Online store: the user asks "how do I pay for the order?", the payment article is found and the button with data-ai-context-id="checkout.payment.submit" is shown.
SaaS form: the user does not understand where to paste a token, and the token field data-ai-context-id from documentation helps highlight the required input.
Account area: the user asks about notification settings, first a menu item on the current page is shown, then the next step after navigation is explained.

In all scenarios, article text stays human: "click the payment button", "enter the token", "open notifications". The context key lives in the span attribute and does not get in the way of reading the instruction.

Example: product card

<main data-ai-area="content" data-ai-section="catalog">
  <article
    data-ai-label="Product: Alpha Sneakers"
    data-ai-kind="product-card"
    data-ai-context-id="catalog.product-card"
    data-ai-kb-query="how to choose product and size"
    data-ai-entity-type="product"
    data-ai-entity-id="sku-alpha-42"
  >
    <h2>Alpha Sneakers</h2>
    <p>Sizes 39-44</p>
    <button
      data-ai-label="Add Alpha Sneakers to cart"
      data-ai-kind="primary-action"
      data-ai-action="cart.add"
      data-ai-context-id="cart.add"
      data-ai-kb-query="how to add a product to cart"
    >
      Add to cart
    </button>
  </article>
</main>

Example: tariffs and payment

<section data-ai-area="content" data-ai-section="pricing">
  <div
    data-ai-label="Pro plan"
    data-ai-kind="plan-card"
    data-ai-context-id="pricing.plan.pro"
    data-ai-kb-query="what is included in Pro plan"
    data-ai-entity-type="plan"
    data-ai-entity-id="pro"
  >
    <h3>Pro</h3>
    <button
      data-ai-label="Choose Pro plan"
      data-ai-kind="primary-action"
      data-ai-action="plan.choose"
      data-ai-context-id="pricing.plan.choose"
      data-ai-kb-query="how to choose and pay for a plan"
    >
      Choose
    </button>
  </div>
</section>

Example: form

<form data-ai-area="form" data-ai-section="checkout-delivery">
  <label for="delivery-city">Delivery city</label>
  <input
    id="delivery-city"
    name="city"
    data-ai-label="Delivery city"
    data-ai-kind="form-field"
    data-ai-context-id="checkout.delivery.city"
    data-ai-kb-query="how to enter delivery city"
  />
  <button
    data-ai-label="Continue checkout"
    data-ai-kind="primary-action"
    data-ai-action="checkout.continue"
    data-ai-context-id="checkout.continue"
    data-ai-kb-query="how to continue checkout"
  >
    Continue
  </button>
</form>

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". Details: document site-actions.md-folder-context-id-ingestion.

How a page action works

Highlight, scroll, click, and fill actions need a specific data-ai-context-id from the documentation. If the path has several steps, the closest available step on the current screen is shown first, then the next one. data-ai-label and data-ai-kb-query help search and explanations, but precise actions need a stable key. If the element is not on the current page or is not described in the documentation, the route is explained in words.

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.

Where this is in the interface

Main elements in this section:

knowledge base page