Runtime configuration

First initialize the widget. Use resolveRuntime to choose settings based on website conditions, or the methods below to temporarily change the current instance.

Runtime parameters

Runtime parameters are temporary state for the current instance. They are not saved to channel settings and reset after destroy() or another init. open(config?) and updateRuntime(config) accept the same configuration:

Parameter	Type	What it changes
welcome	object | null	Greeting selection: { mode: "centered_text" } or { mode: "automation_message", automation_id, node_id } from messages allowed in channel settings. null restores the greeting from channel settings. An existing dialog keeps its history; the selection applies to the next new dialog.
lang	"ru" | "en" | "auto"	Interface language.
display_mode	"popup" | "embedded"	Placement mode. The embedded container must already be provided during init.
surfaceVisible	boolean	Reports whether the visitor can see the container. false pauses read receipts without hiding the container or stopping requests. Hideable panel example.
theme_mode	"light" | "dark" | "auto"	Current instance theme.
border_radius	number	Current-instance rounding from 0 to 50.
shell	object	collapse_button and mobile_edge_swipe.
customActions	object	Complete set of available site actions and their browser-side handlers. Setting returnsResult: true on an action allows the agent to invoke it and receive its result.
customActionsLanguage	"ru" | "en"	Action-description language.
autoExecuteCustomActionNames	string[]	Action names allowed to execute automatically in the current scenario.
dialogId	string	Existing dialog to select.
startNewDialog	boolean	Creates a new empty dialog when true.
focusInput	boolean	Focuses the message input when true.
pageContextItems	array	Replaces persistent page context. setPageContext(items) is clearer for navigation.
contextItems	array	Supplies one-time context for the next message.
message	object	Prepares or automatically sends a message.

Parameter constraints

When dialogId is supplied, the widget selects that dialog; the ID must be a non-empty string of no more than 200 characters. startNewDialog: true creates an empty dialog, while message.startNewDialog: true sends without the current dialog_id. If dialogId and either form of startNewDialog: true are supplied together, the new dialog wins, so do not combine those intentions in one call. Do not treat autoExecuteCustomActionNames as persistent permission: supply it again in each scenario that needs automatic execution. Matching buttons are hidden; the widget automatically executes only the first matching action in a response.

autoExecuteCustomActionNames accepts no more than 20 unique names. Each name follows the same rules as a custom action name: 1–120 characters, starting with a Latin letter, followed by Latin letters, digits, _, ., :, or -. A duplicate name makes the configuration invalid. List only declared actions: a name without a corresponding customActions entry cannot invoke a site handler.

message accepts { text, requestId?, startNewDialog?, autoSend? }. Text must be a non-empty string up to 10,000 characters. requestId must be a non-empty string up to 200 characters. autoSend: true sends after the widget becomes ready; false or omission only places text in the input. Omit requestId for that draft-only case: result events are intended for automatic sending, and the loader reports a failure if the visitor does not start the request within 10 seconds.

An unknown runtime key, invalid type, or out-of-range value causes a synchronous call error. In production code, pass only fields from this table and catch errors around dynamically assembled configuration.

In an SPA, do not call destroy() and init() again on every transition. Update the page through setPageContext(items) and use open({ contextItems, message }) for a targeted scenario.

See Sending messages from a website for a complete sending and error-handling example. Readiness and startup callbacks are described in Widget events.