Context Item Format

This format is shared by page context and individual message context.

Pass only data this visitor is allowed to see. Do not include secrets, tokens, or payment data. Context does not grant permission to perform actions.

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.

Page links from history

To link from a tag, provide ref.url or ref.route. A non-empty ref.url takes priority. When passed through the loader, a relative address such as /orders/123 becomes an absolute URL relative to your website's page. A link in the saved conversation therefore opens the order on your website, not the same path inside Senler.

When passing data directly without the loader, use a full URL starting with https:// or http://. If saved context contains only a relative route without a domain, it cannot be opened as a link: the original website cannot be identified reliably. Other protocols, including javascript:, do not become links in history. The context itself remains available to read.

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.