Website Widget Connection

Summary

Path: Channels item in the side menu -> channel list -> Add channel -> Widget.

This guide takes you from creating a channel to installing the chat on a site. If the channel already exists, start by checking its domain in the settings, then configure its appearance and copy the generated code.

Creation form

1. Select Widget in the channel-type list.
2. Enter a clear widget name, such as the site or section name.
3. In allowed site domains, enter the domain where the chat will run.
4. Click the add button with a plus to add the entered domain to the list. If you make a mistake, remove an unnecessary domain.
5. Click Create Widget to create the widget channel.

Domains

An allowed domain determines which site may run this channel's code. It prevents the widget from being used on unrelated sites. Enter the address without a protocol or path, for example example.com; you can use a mask such as *.example.com for subdomains.

When creating a channel, add the domain directly in the form: enter it and click the plus button. You can change the list later in the created channel's settings.

Channel Name, Icon And Domains

On the channel settings page, in the widget block, click edit name, change the name or icon, then click Save. Cancel closes editing without saving.

The name and icon affect how the channel appears in the cabinet and lists. To change the icon, first enable name editing: after that the icon area becomes available for file upload.

Allowed domains define which sites can run the widget code. Remove an unnecessary domain with the delete button. To add a new one, click Add domain, fill the domain field, and confirm the addition or click Cancel. If the site is opened on a domain that is not in the list, the widget may not start or may not accept the connection.

After creation

After creation, the cabinet opens the new channel's settings. Work through them from top to bottom, configure the appearance and chat features, and click Save. The generated site snippet is farther down in Embed Code. Copy it in full and insert it before the closing </body> tag on the site.

Widget settings

• channel name;
• icon;
• allowed domains;
• color scheme: light, dark or auto;
• language: Russian, English or auto;
• display mode: popup window or embedded widget;
• popup window position: top left, top right, bottom left or bottom right;
• window width from 200 to 800;
• window height from 300 to 1000;
• rounding radius from 0 to 50;
• shadow;
• texts in Russian and English;
• welcome screen buttons in Russian and English;
• button settings;
• chat function settings;
• external AI connection through MCP;
• embed code.

Window And Appearance

Display mode defines how the widget appears on the site:

• Popup - the widget opens from a floating button and shows a window over the page;
• Embedded - the widget is embedded into a page container without a floating button.

For a popup, choose its position: top left, top right, bottom left, or bottom right. Width is limited to 200-800 px and height to 300-1000 px. Enter an exact value in the numeric field, or use the width slider and height slider for visual adjustment. Corner radius works for both popup and embedded modes; it can also be changed with the radius slider. The Shadow switch enables or disables the shadow around the window.

Color scheme sets light, dark, or automatic mode. In automatic mode, the widget follows the user's browser settings. Language can be set to Russian, English, or Auto.

Rounding changes immediately in preview but is saved only after the save button is clicked. With dynamic code, the saved border_radius is loaded from the server. With static code, replace the code on the site after saving. To change an already running instance temporarily, a developer can call SenlerWidget.updateRuntime({ border_radius: 18 }); this value is not written to channel settings.

Widget texts

• chat title;
• standard dialog title;
• input field hint;
• welcome message;
• buttons with ready-made first-message options.

Texts are configured separately on the Russian and English tabs. A tab changes only the text version being edited, not the overall widget language.

On the Russian tab, set the chat title, default dialog title, input placeholder, and welcome message. The English tab provides the same fields: chat title, default dialog title, input placeholder, and welcome message.

The chat title is shown in the widget header. The default dialog title is used until a dialog has its own title. The placeholder is visible before typing, and the welcome message is shown in an empty chat before the first message.

In Welcome screen buttons, select the RU or EN tab and add first-question options. The Russian field and English field accept up to 8 unique buttons, each no longer than 120 characters. The widget shows only the list for its current language; if that list is empty, no buttons appear.

Visitors see these options below the welcome message before the conversation starts. Clicking one immediately sends its text as the visitor's message. While it is being sent, the other options are temporarily disabled to prevent duplicate requests.

Widget Button

Button Position

The widget button exists only in Popup mode. Place it at the top left, top right, bottom left, bottom right, or hide it. If the button is hidden, the widget can only be opened programmatically from the site.

Button Colors

For the light theme, choose the background in the palette and refine it in the HEX field when needed, then set the icon color in the palette and its HEX field. For the dark theme, use the background palette, background field, icon palette, and icon field.

Closing And Collapsing

In popup mode, the close button is already available in the widget header, so you do not need to add it separately. SenlerWidget.close() hides the window, and SenlerWidget.open() shows it again.

In embedded mode, the regular close button is hidden. A developer can enable a collapse button inside the header with shell.collapse_button: true. Clicking it calls onCollapse(detail) and dispatches senler-widget:collapse-request, but does not hide the widget automatically. The site chooses one handler and calls SenlerWidget.close() or closes its outer panel. SenlerWidget.open() shows the hidden widget again. A complete example is available in the Public API guide.

SenlerWidget.destroy() is not a collapse operation: it completely removes the instance, so another initialization is required.

Chat features

• file upload;
• voice messages;
• emoji;
• split view of the dialog list and chat;
• chat history in the widget header;
• chat history search;
• page element selection.

Switches in the "Chat features" block control what the site user sees:

• File upload allows sending files through the widget;
• Voice messages enables recording and sending voice messages;
• Emoji shows the emoji picker;
• Split window into dialog list and conversation shows the dialog list next to the selected chat on sufficiently wide screens;
• Page element selection shows the element picker button and sends the selected site place together with the user's question.

Visitor credit limit

When a personal limit applies to this channel:

1. Find the Credit limits section in the channel settings. It displays the rules that actually apply to the widget: the project's default periods or the channel's custom periods.
2. Click Configure project limits to change the periods, make this channel unlimited, or assign custom rules to it.
3. If needed, enable Offer additional credits. This switch adds a top-up button to the exhausted screen.

When the limit is enabled, a ring indicator of the available amount appears in the chat header. Selecting it opens details for every period: the remaining amount, total limit, and start time of the next period. If the lead received extra credits, their remaining amount and the total available amount appear below.

After exhaustion, Credits used up replaces the input field and the agent no longer starts for this lead in this channel.

After the limit is exhausted, the widget owner can offer the visitor one or both ways to continue:

• Add credits — the button sends a request to the website, where the owner opens a custom payment form and grants extra credits to the lead after a successful operation. Event setup and source validation are covered in Credit top-up request.
• Connect your AI — the button opens instructions for connecting the project's selected MCP server to a compatible AI client. Setup and connection methods are covered in Use via MCP.

These are independent options: connecting MCP lets the visitor work with the service from their own AI client and does not by itself grant extra credits for continuing the conversation in the widget.

Use via MCP

Enable Show the Use via MCP button and select an active project MCP server. Manage opens the project's MCP server settings. The feature cannot be saved while enabled without an active selected server.

To show ready-to-run commands for the ChatGPT app and Codex CLI, enable Show ChatGPT installation, enter an HTTPS Git marketplace URL without query parameters, and enter the plugin ID in plugin@marketplace format. The ChatGPT tab appears only when both the URL and ID are present and valid; the other connection methods remain available independently.

After saving, an MCP button appears in the toolbar below the message field. It opens the selected server URL and instructions for different AI clients. The button is next to the chat actions rather than in the widget header.

Connection Methods

• Universal: copy the MCP URL and add it as a remote MCP server in a compatible AI client;
• ChatGPT: copy the two installation commands, run them in a terminal, and open a new Codex task in the ChatGPT app or CLI;
• Claude: copy the MCP URL, then add a custom connector under Customize → Connectors. Open Claude takes you directly to Connectors. On Team and Enterprise plans, an organization owner adds the server first;
• VS Code: copy the MCP URL, run MCP: Add Server, select a remote HTTP server, and choose the Global or Workspace scope;
• Cursor: select Add to Cursor. The selected MCP server's URL and name are passed to the installation. If Cursor does not open, copy the URL and add the server manually through MCP settings.

On first connection, the AI client prompts for authorization or shows an authorization link when the server requires sign-in.

Authorization

A normal connection uses OAuth: the AI client or the Senler connection page handles sign-in, account selection, and connection changes. The agent does not receive separate tools for entering a token, disconnecting an account, or switching projects. To choose another account, open connection management in the AI client and complete authorization again.

Access Key For A Client Without OAuth

If the AI client can send a Bearer token but cannot complete OAuth, use the For clients without OAuth section. This method is available for a selected managed Senler MCP server; for an arbitrary MCP URL, use that server's own authorization method.

1. Select Sign in and create key.
2. Sign in to the connected service in the pop-up window and complete authorization.
3. Copy the created key immediately: its full value is shown only once.
4. Keep the same MCP URL and pass the key from the AI client as Authorization: Bearer <key>.

Active keys belong to the current widget visitor and the selected MCP server. If a key is no longer needed or may have been exposed, select Revoke key next to it. A revoked key can no longer connect; to use another account, create a new key after authorizing that account.

Preview And Saving

• the window preview shows how the widget will look on the site;
• the button preview shows the floating chat launch button;
• the preview status icon shows whether the preview is starting, applying changes, synchronized, or in an error state. Select it to see the window and button states;
• on a mobile screen, the Widget, Button, and Settings tabs switch between the window preview, button preview, and settings form;
• after changing settings, click the save button.

The preview helps check theme, dimensions, rounding, texts, and colors before updating the widget on the site. When you change the header, new-dialog title, or empty-state text, it switches to the relevant screen for about 10 seconds and then returns to a regular conversation. Changing the input placeholder or chat features immediately returns the preview to the conversation where those changes are clearer.

After a setting changes, the preview tries to apply it immediately. “Preview is synchronized” means the change was applied by every preview part required for the selected mode: in popup mode, this is the window and button; in embedded mode, only the window. It does not mean the setting has already been saved to the channel. With static code, save, copy the new code, and update it on the site. With dynamic code, saved changes are applied from the server automatically.

If the preview ends with an error, open its status. You can copy diagnostics for support or select Retry. Retry applies only to the preview and does not send a message to the visitor.

Chat history in the widget

All visitor-facing controls and states are described separately in Website Widget Interface.

• if the site user already has dialogs, the widget may automatically open the current dialog on first entry;
• a chat history button is available in the chat header;
• the history menu can open the full chat list, create a new dialog, or find a dialog through search;
• history search starts from two characters;
• unread messages are shown as a counter on the dialog.

Embed code

• can be static or dynamic;
• if the user changes the settings, you need to update the code on the site if static code is used;
• with dynamic code, changes are applied automatically.

Appearance change mode selects how the site receives settings:

• Static - settings are embedded directly into the code. After changing appearance, copy the new code and update it on the site;
• Dynamic - the site loads settings from the server. Changes apply without replacing the code if the code itself is already installed correctly.

Enable linking the lead to website authentication only when the site server will pass signed user data. The ready embed code is read-only. Change the settings above, wait for the code to refresh, open the user data example when needed, and then use the copy button.

Code Building Example

The example preview field updates immediately after every selection.

In the code building example, you can include email, phone, first name, last name, avatar URL, and additional user.data parameters. The current server accepts phone but does not persist it in the lead profile; see the parameter reference for the exact behavior of every field.

Selecting fields in the example does not change the main generated code in settings. For an additional parameter, fill in its key and value; use Add to create another pair and remove an unnecessary one. These values provide personalization and context such as plan, city, current site section, traffic source, or other data that helps the operator and agent understand the user.

Check the selected data, then use the separate copy button.

Opening The Widget And Site Context

This section is for the site developer when the site should open the widget itself, pass a message, pass current page data, or show site actions in the chat. If you only change the widget appearance in the cabinet, you can skip this section: save the settings and update the code on the site when static mode is used.

After installing the code, the developer can use additional widget capabilities:

• initialize the widget once on the site after installing the code;
• open, close, or toggle widget visibility in popup or embedded mode from a site event;
• show a collapse button in an embedded widget and handle the collapse request on the host site;
• select an existing dialog without sending a new message;
• open the widget immediately with message text or context for the next question;
• pass persistent context for the current page, card, order, or project;
• update context, message, or available actions without reinstalling the widget;
• temporarily change theme_mode, border_radius, display_mode, and shell parameters through updateRuntime;
• declare site actions through customActions, so the agent can show a button in the chat and the site performs the action on its side;
• connect an AI text-edit scenario in a site field: the site shows its own UI, while the widget creates the dialog and returns the edited variant;
• set the language of site action descriptions through customActionsLanguage if they are written only in Russian or only in English;
• remove the widget from the page if the site manages the widget lifecycle itself;
• link the chat to an authorized site user through external_id and user_hash.

Action names and passed data should be clear to the user and operator. If you need to pass the current page without manual element selection, use page context. If you need to let the agent perform an action on the site, use site actions.

Detailed methods, parameters, and examples are in the site developer instructions.

Important To Remember

• the floating button can be hidden, but the widget window itself cannot be hidden this way;
• if you need to remove the button from the site, choose the "Hidden" button position;
• embedded mode does not use the floating button;
• close() hides the widget while keeping its instance and dialog state, while destroy() removes the widget completely;
• the shell.collapse_button button only requests collapsing, so the site must handle onCollapse or senler-widget:collapse-request.

Linking To An Authorized User

• needed to link a site user to an authorized account;
• includes a secret key;
• the secret can be shown, copied or regenerated;
• regenerating the secret is dangerous: the old key stops working immediately;
• if linking to authentication is enabled, external_id and user_hash are needed in the code;
• in the code example you can specify email, phone, first name, last name, avatar and additional data fields.

The Link lead to website authentication switch is needed when the user should see conversation history after signing in from another device or browser. Enabling it requires the site developer: the site must pass the user's external ID and user_hash signature.

Keep the secret key only on the site server. You can show or hide it, copy it, or regenerate it. Regeneration immediately disables the old key, so prepare the server update first. In the confirmation dialog, you can cancel the replacement or confirm it.

If linking is enabled, the cabinet shows server-side code examples for signature generation. Select the example language and copy the required snippet.

Element selection

• is enabled with the "Page element selection" switch in chat feature settings;
• sends the context of the selected place on the site with the message;
• helps the agent understand which button, field, card, or page block the user is asking about;
• usually it is enough to add clear labels to important site elements without a separate app change;
• see site element markup for details.

If the widget is not displayed on the site

• check whether the code is inserted into the site;
• check the allowed domain;
• check if the script is blocked by site policy;
• check the widget display mode;
• check the browser console;
• check the agent's purpose and channel status.