Page Context

Context is explicit data attached by the site so the agent understands the current situation. Examples are “Checkout is open” and “The user is asking about order 123.” Start with one page-context item and add business objects only where they are useful.

Data Sent with the Message

The message includes complete context items: their kind, role, readable label, and any supplied ref, snapshot, and payload objects. Before sending, the visitor sees items without hidden: true in the message field's Context menu. After sending, visible items appear as chips beside the message. Hidden items are also stored and sent to the agent.

Context does not read arbitrary page state. Senler supplies system data for the current lead separately from the lead profile; orders, projects, and other site data must be added explicitly. Do not add secrets, tokens, payment details, or information that this visitor must not see. If an agent instruction needs an exact lead ID or profile field, use system lead variables instead of duplicating values in every contextItems array.

Choose the Context Type

• Page context for the chat UI is provided through contextProvider during SenlerWidget.init and replaced through SenlerWidget.setPageContext(items) during navigation. It is offered with subsequent messages the visitor sends from the composer.
• Programmatic request context is passed explicitly as contextItems in SenlerWidget.ask({ text, contextItems }). This call does not pick up chips from setPageContext, draft context, or the element selected in the UI.
• Shared JSON context for ask is set through setContext; the context option extends or overrides it for one request.

If the visitor should write a question about an object, pass one-time contextItems to selectDialog or startNewDialog. They appear in the composer and move to the message when it is sent. If sending fails, the message's Retry button uses the same context; it does not need to be attached again.

An example for a specific order is in message context; all fields, limits, and merging rules are described in the context item format.

Pass the Current Page

contextProvider is called once during initialization and must synchronously return a ready array. Promises are not supported. If the page title or entity loads later, return a basic item first and call SenlerWidget.setPageContext(items) after loading.

Passing a non-function value makes init fail synchronously. If the function itself throws or returns an invalid array, the loader writes [SenlerWidget] contextProvider callback failed to the console and continues startup without that context. Verify the page chip separately in the running widget.

function buildPageContext() {
  return [
    {
      id: `page:${window.location.pathname}`,
      kind: "page",
      role: "technical",
      display: {
        label: document.title || "Current page",
        subtitle: window.location.pathname,
      },
      ref: {
        url: window.location.href,
        route: window.location.pathname,
      },
    },
  ];
}

SenlerWidget.init({
  channel_id: "xxx",
  contextProvider: buildPageContext,
});

In an SPA, replace context after every route change without reinitializing:

SenlerWidget.setPageContext(buildPageContext());

setPageContext(items) replaces the entire persistent context; it does not append to the previous array. Always pass the complete current set. Call SenlerWidget.setPageContext([]) to clear persistent context.

For a programmatic question about the same page, pass the current array directly to ask:

await SenlerWidget.ask({
  text: "Help me understand the current page.",
  contextItems: buildPageContext(),
});

JSON context

If your integration only needs one object without separate entity chips, use SenlerWidget.setContext(context):

SenlerWidget.setContext({ section: "orders", orderId: "123" });
const result = await SenlerWidget.ask({
  text: "Explain the order status.",
  context: { orderId: "456" },
});

This request keeps section: "orders" and overrides orderId with "456". Merging is shallow: a nested object in the request replaces the corresponding object entirely. The context option on ask does not change the persistent value.

Each ask call captures its own data snapshot before queueing. Later navigation does not change that request. JSON objects are limited to 16,000 bytes and 8 nesting levels; functions, circular references, and unsafe key names are rejected.

setContext also replaces persistent context chips in the chat UI with a single Context chip. Choose one way to manage persistent context: a later setPageContext call changes the UI chips but does not clear the JSON stored for ask. For multiple chips, custom labels, or hidden, use setPageContext for manual sending and pass contextItems explicitly to ask. Calling setContext({}) clears both the stored JSON and persistent chips.

When to Update Context

• Call setPageContext after navigation to another page.
• Pass a new complete array when a different card opens on the same route.
• Use contextItems for one question without replacing persistent context.
• If visitors should select a button or field themselves, enable element selection instead of constructing a selected-element item manually.

What to Configure Next

Once page and business-object chips are correct, add stable data-ai-* markup to important buttons, fields, and cards. Context explains the situation to the agent; markup links an answer to an exact site element.