How to Configure Widget in Settings

The widget can be configured in ConnectiveOne Settings. Here you will generate embed code, configure CORS domains, add Custom Code, set a custom icon for the Operator Panel, and configure other parameters.

Where to Find Settings

Path: Settings → Bots → select bot → Widget

Generating Embed Code

  1. Go to Settings → Bots → select bot → Widget
  2. Configure widget appearance in the constructor (if needed)
  3. Copy the generated HTML+JS code
  4. Insert the code on your website

💡 Tip: Code is generated automatically based on your settings. You can change parameters and copy the updated code.

Configuring CORS Domains

To connect the widget on the website, you need to add your site's origin to the allowed list. The system stores the list as a JSON array of full origin URLs.

Where to configure

  • Settings → Bots → select bot → Widget — section "List of allowed domains for installing the widget".
  • Scenario Builder → Widget channel configuration in the start node.

Origin format

  1. Enter the full origin URL with protocol: https://www.example.com or http://localhost:3000.
  2. No trailing slash: not https://www.example.com/.
  3. No path or query: not https://www.example.com/page and not https://www.example.com?ref=1.
  4. Only http: or https: — other protocols are not supported.

Examples:

  • Correct: https://shop.example.com, https://www.example.com, http://localhost:5173
  • Incorrect: example.com, www.example.com, https://example.com/, ftp://example.com

Steps in the editor

  1. Open one of the sections above.
  2. Click "Add domain" and enter the origin (placeholder: https://www.example.com).
  3. Add every origin you need (for example, https://shop.example.com and https://www.shop.example.com are different origins).
  4. Remove a row with the delete icon if a domain is no longer needed.
  5. Click "Save CORS" (or the channel save button in bot settings / Scenario Builder). The button stays disabled while any URL in the list is invalid.

⚠️ Important: Without adding the origin, the widget cannot connect to Socket.IO from your site. If the instance still has a list saved in an old format (comma-separated text), the system may use it temporarily on read — save the list again through the editor to lock in the correct format.

Configuring Custom Code

Custom Code allows adding custom JavaScript code that executes before widget initialization.

  1. In the Widget section, find Custom Code
  2. Enter your JavaScript code
  3. Save settings

Custom Code Example:

// Modify parameters before initialization
embed_state.params_from_site = {
  ...embed_state.params_from_site,
  page_url: window.location.href
};

// Integration with Google Analytics
if (window.gtag) {
  window.addEventListener('widgetChatOpened', function() {
    window.gtag('event', 'widget_chat_opened');
  });
}

Available Objects in Custom Code:

  • embed_state — widget state before initialization
  • kw_event() — function to call events
  • kw_event_trigger() — function to trigger events

Custom Widget Icon in Operator Panel

You can set a custom icon for the Widget channel that will be displayed in the Operator Panel next to chats from this widget. This helps operators visually distinguish message sources (e.g., website widget vs. PWA app).

  1. Go to Settings → Bot Settings → Hooks → Widget
  2. Find the widget badge_url field (custom icon URL)
  3. Enter the full image URL (e.g., https://example.com/icon.png)
  4. Save settings

Result: In the Operator Panel chat list, your icon will be shown instead of the default widget icon.

💡 Tip: If the URL is invalid or the image is unavailable, the system will display the default widget icon.

⚠️ Limitation: One icon per bot. To distinguish multiple entry points (e.g., website and PWA), create separate bots for each source.

This setting is also available in Scenario Builder when configuring the Widget channel in the scenario start node.

Configuring Widget Version

The widget is available in two versions:

  • V2 (current, recommended) — used by default
  • Legacy (compatibility mode) — only for supporting old integrations

Where to find: Settings → Bot Settings → Hooks → Widget → parameter v2_mode and v2_value

💡 Recommendation: Use V2 for all new integrations.

Configuring Colors

Widget colors can be configured:

  1. Through Widget Demo (/widget/{locale}/?bot-id={bot_id}) — visual constructor
  2. Through the colors parameter during widget initialization
  3. Through kw_event('kwcolor', {...}) during operation

📖 More details: See Customize widget colors