Widget JavaScript API

ConnectiveOne widget provides a JavaScript API for controlling widget behavior from your website. This allows programmatically opening/closing chat, changing parameters, passing events to the scenario, and integrating the widget with SPA applications.

Main Functions

Widget Initialization

kw('init', {...}) — initializes the widget with parameters.

Parameters:

• bot_id — bot identifier (default 1)
• user_id — user identifier (optional, generated automatically)
• language_code — interface language (uk, ru, en, etc.)
• params_from_site — additional parameters for the scenario
• colors — widget color scheme
• open_on_msg — automatically open chat when receiving a message
• recognize_user_meta — collect client data for the operator panel and Statistics: enabled by default (true). Adds IP address, user agent, auto-detected launch platform (source_platform), and embedding page hostname (source_hostname). Set to false to disable
• move_to_body — optional stability flag for floating widget mode. Default: false. When set to true, the widget moves its rendered root to document.body and removes duplicate empty #kwizbot_widget placeholders created by the host page. Do not use it for inline or frame placement

Example:

kw('init', {
  bot_id: 1,
  language_code: "uk",
  params_from_site: {
    utm_source: "widget",
    company_name: "TV123"
  }
});

Chat Control

kw_event('openchat', 1) — open chat

kw_event('openchat', 0) — close chat

Example:

// Open chat on button click
document.getElementById('open-chat-btn').addEventListener('click', function() {
  kw_event('openchat', 1);
});

Changing Title and Subtitle

kw_event('command', { title: '...', subtitle: '...' }) — change chat title and subtitle

Example:

kw_event('command', {
  title: "New Title",
  subtitle: "New Subtitle"
});

Navigate to Scenario Entry Point

kw_event('emitevent', { event: 'alias', alias: 'test-alias' }) — navigate to the specified alias in the scenario

Example:

kw_event('emitevent', {
  event: 'alias',
  alias: 'product-inquiry'
});

Pass Parameters from Website

kw_event('kwsetparamsfromsite', { params_from_site: {...} }) — change parameters during operation

Example:

kw_event('kwsetparamsfromsite', {
  params_from_site: {
    company_name: 'TV123123',
    page_url: window.location.href
  }
});

Change Colors

kw_event('kwcolor', { header: { bg: '#FF0000' } }) — change widget colors

Example:

kw_event('kwcolor', {
  header: {
    bg: "linear-gradient(130deg, #734FE1, #D14EE0)",
    text: "#ffffff"
  }
});

Working with SPA

kw_event('kwreinitwidget', {...}) — reinitialize widget (for SPA)

Parameters:

• user_id — change user (or null for new chat)
• params_from_site — update parameters
• title, subtitle — change title

Example:

// Create new chat
kw_event('kwreinitwidget', { user_id: null });

// Change parameters
kw_event('kwreinitwidget', {
  params_from_site: { type: 'mobile' }
});

kw_event('kwvisiblelauncher', { visible: false }) — hide/show launcher

Example:

// Hide launcher
kw_event('kwvisiblelauncher', { visible: false });

// Show launcher
kw_event('kwvisiblelauncher', { visible: true });

Save State

kw_event('widgetstatus', 1) — save chat state in localStorage

After execution, the following is saved in localStorage:

• isChatOpen — widget state (collapsed/expanded)
• connectState — operator connection state

Widget Events

You can listen to widget events:

widgetChatOpened — chat opened

widgetChatClosed — chat closed

Example:

document.addEventListener("widgetChatOpened", function(event) {
  console.log('Chat opened', event);
  // Your handling code
});

document.addEventListener("widgetChatClosed", function(event) {
  console.log('Chat closed', event);
  // Your handling code
});

Custom Code

You can add custom JavaScript code that executes before widget initialization. The code has access to:

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

Where to configure: Settings → Bots → select bot → Widget → Custom Code

Custom Code Example:

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

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

Limitations

• Only one widget instance can be on one page
• Widget works only through HTTPS (except localhost)
• Domains for widget must be added to CORS settings
• Spam protection: automatic blocking at 10+ messages in 5 seconds

Related Articles

• What is a widget
• Connect widget to website
• Pass parameters from website to scenario
• Manage widget from website
• Work with SPA applications
• Use Custom Code
• Data exchange with widget