How the Widget Integration Works

After the regular connection is working, the widget can be linked to the website interface. The agent can then understand which page or entity is open, the visitor can ask about a particular element, and the website can perform a predefined action.

Three Parts of the Integration

• Context tells the agent where the visitor is and which object matters. For example, “The payment section is open” or “Order 123 is open.”
• Markup gives important page elements stable keys and connects them with phrases in the documentation.
• Actions let the widget ask the page to highlight an element, scroll to it, change a field, or run a separate website handler.

These parts can be added independently. If the agent only needs to know which page is open, start with context. Markup and actions are needed when visitors should select elements or interact with the interface through the widget.

Information Available When Preparing a Reply

The lead profile, agent instructions, and context explicitly passed by the website to the widget may be used to prepare an answer. Arbitrary JavaScript state on the page is not read automatically.

If the agent needs an order number, product name, or another property of the open entity, add it to page or message context. Data and Variables in an Agent lists the system lead fields that can be inserted into agent instructions.

What a Complete Connection Looks Like

Suppose the website has a payment button:

1. The website passes context: the visitor is on checkout and order 123 is open.
2. The button receives the stable key checkout.payment.submit by following Site Element Markup.
3. The same key wraps a natural phrase in a Markdown guide: “Click the payment button.”
4. The visitor selects the button and asks a question. The widget sends the selected element with the message.
5. The agent finds the linked guide and explains the action. If the website supports the scenario, the widget can show the element or perform an allowed action.

Start with one simple scenario: one page, one element, and one linked phrase. After verifying it, add more elements, custom actions, inline edits, and Public API methods.

Website Security and Responsibility

The browser may receive the loader-script URL, channel_id, interface settings, visitor data, and an already computed user_hash. The channel secret used to create the signature and all project API keys must remain on the website backend.

Message context, visible element text, and data-ai-* values are sent to Senler AI. Do not put passwords, tokens, payment details, or other secrets in them.

Treat every payload received by a customActions handler as untrusted. The website must validate its types, user, permissions, and allowed operation again. Payment, deletion, and other significant actions remain subject to the website's own confirmation UI and backend checks.

What to Check After Website Changes

If a button, field, or menu is moved or renamed, check its markup, the linked phrase in the documentation, and the action scenario together. Change a stable data-ai-context-id only when the meaning of the element changes, not when its label or location changes.