Widget initialization

First create a channel and obtain the code in Embed Code. If the cabinet settings are sufficient, paste the generated code unchanged. This page is for developers who embed the chat in their own container, pass authenticated visitor data, or control configuration from code.

Where to Start

Choose placement: over the page (popup) or inside your own block (embedded). Appearance and features come from saved channel settings. If a particular site needs different values, pass only those overrides in theme and features when calling init.

Placement Mode

• popup opens over the page from a floating button;
• embedded occupies the supplied container and has no floating button.

For embedded, pass an existing CSS selector or DOM Element. Initialization fails if the container cannot be found. open(), close(), and toggle() work in both modes.

button_only: true renders only the floating-button appearance without a chat iframe. The button is not interactive, open(), close(), and toggle() open nothing, and isOpen() returns false. This mode is intended for a standalone button preview and cannot be combined with embedded. Because no iframe is created and remote channel settings are not loaded, define its appearance through theme.button in the site code.

For a fully custom chat interface, set headless: true during initialization. The SDK remains available, the built-in chat and floating button stay hidden, and a hidden iframe handles authentication and requests. open() and toggle() do not show this instance. This option is incompatible with embedded and button_only and cannot be changed through configure. History queries and subscriptions also work in the normal widget without headless.

Configuration Priority

For theme and features, there is one order: defaults → channel settings → explicitly supplied init fields. For example, theme: { height: 700 } fixes the popup height at 700 px while width, colors, text, and features come from channel settings.

Nested objects merge field by field: overriding the Russian title preserves the English one, and a button background color does not erase its icon color. Omitted fields and undefined do not replace values from channel settings. Explicit false, a valid 0, and empty arrays are preserved; arrays replace the entire list for the specified language. Empty localized text is not used as an override. For welcome_icon_url, an empty string has a specific meaning: restore the default icon.

SenlerWidget.init({
  channel_id: "xxx",
  theme: { height: 700 },
  features: { voice_messages: false },
});

Code generated in the cabinet does not include a full snapshot of theme and features. Saved changes to channel settings apply on the next widget initialization, except for fields explicitly fixed in site code. The cabinet preview also shows unsaved changes, but it does not change the configuration of the live site. Language and placement are set separately in the integration code.

In a running widget, supported parameters can be temporarily replaced through configure. When selection based on website conditions is configured, fields returned by resolveRuntime override these base settings until the next evaluation.

Configure the capabilities you need

• Embedding in a container: panel dimensions, chat visibility, the collapse button, and the mobile gesture.
• Appearance in code: theme, text, buttons, and the greeting image.
• init reference: parameters and chat features.
• Visitor identity: external ID and server signature.
• Greeting in code: selecting a greeting and sending automation messages.
• Settings based on website conditions: selecting the greeting, language, and appearance based on visitor and page data.

After initialization, use runtime configuration without recreating the widget.

If Loading Is Delayed

The progress indicator appears when loading exceeds 4 seconds. After 10 seconds, the loader displays “Loading is taking longer. We are still retrying.” and a Copy for Support button. This is informational: automatic retries continue.

The report contains loader and protocol versions, attempt number, duration and failure stage, network state, and resource checks. Query parameters, request contents, channel and user IDs, and tokens are excluded.

The external report covers iframe startup. If an error occurs inside an already loaded chat, use the action shown in that particular interface message.

What to Configure Next

After initialization works, pass the current screen and relevant business object through page context. For data that belongs to a single question, use message context. Start marking buttons and fields only after an ordinary message and context work independently.