Widget Page and Message 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. The visitor sees their labels as chips above the input and beside the sent message.

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

• Persistent page context is provided through contextProvider during SenlerWidget.init and replaced through SenlerWidget.setPageContext(items) during navigation.
• One-time message context is passed as contextItems in SenlerWidget.open({ contextItems, message }) or SenlerWidget.updateRuntime({ contextItems, message }).

Persistent context describes the current screen and is offered with subsequent messages. One-time context describes a specific order, recommendation, or target for the current question and is removed from the draft after a successful send. It remains available after a send error so the visitor can retry.

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.

Add the Object for This Question

Pass contextItems when opening chat for a specific entity or action:

SenlerWidget.open({
  contextItems: [
    {
      id: "order:123",
      kind: "order",
      role: "business_context",
      display: {
        label: "Order #123",
        subtitle: "Open card",
      },
      ref: {
        entity_type: "order",
        entity_id: "123",
        route: "/orders/123",
      },
      snapshot: {
        status: "awaiting_payment",
        total: "$49.00",
      },
      payload: {
        available_actions: ["pay", "cancel"],
      },
    },
  ],
  message: {
    text: "Describe what I can do with this order.",
    startNewDialog: true,
    autoSend: true,
  },
});

In this example, the visitor sees an “Order #123” chip, while the order ID, route, state, and available actions are included with the question. These are data for the answer, not permission to perform payment or cancellation. One-time context is cleared only after a successful send. Persistent page context remains available for later messages.

Describe Each Item

Field	Type	Required	What to pass
id	string	Yes	Stable item ID, such as order:123.
kind	string	Yes	Entity type, such as page, order, or product.
role	string	Yes	Item purpose from the list below.
display.label	string	Yes	Short, readable chip label.
display.subtitle	string	No	Additional explanation in the chip.
display.icon	string	No	Reserved string identifier up to 40 characters. The current interface chooses a standard icon from kind and does not render this value.
display.avatar_url	string	No	Image URL.
ref	object	No	Stable IDs, a route, or URL used to locate the current object.
snapshot	object	No	Object values captured at send time.
payload	object	No	Additional JSON data defined by your integration.

role value	When to use it
technical	The current page or a service part of the scenario.
user_selected	An object explicitly selected by the visitor.
business_context	The order, product, project, or other business object in the question.
action_target	The object that the visitor intends to change.

A role describes the purpose of an item; it does not grant permission to perform an action. After persistent context, one-time context, and a selected element are combined, a message must contain no more than 12 items.

Limits: id up to 120 characters, kind up to 80, display.label up to 80, display.subtitle up to 140, display.icon up to 40, and display.avatar_url up to 500. ref, snapshot, and payload must be JSON-compatible objects.

Check the Chips Before Sending

Use IDs such as page:/orders/123, project:019..., and order:123. If the same object comes from both page context and contextItems, a matching id leaves one tag. Give different entities different kind and id values even when their labels are similar.

Persistent context, one-time contextItems, and selected-element context are combined in that order and deduplicated by id: a later item with the same ID replaces the earlier one. A one-time item can therefore refine a persistent item, and the selected element can refine either. The visitor can remove any chip from the draft before sending.

After sending, context chips remain in dialog history as read-only information. They can be expanded and, when links are supplied, open ref.url or ref.route. Only supported details are displayed, so do not rely on every arbitrary payload field being visible.

Selected Element Context

An element selected through features.element_selection is added as an ordinary item with the selected_element type. Do not pass it again through contextItems.

Add data-ai-* attributes to page elements so the context has a clear label, purpose, and documentation link. See Site Element Markup and Highlighting and Actions.

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.