Widget settings parameters

This page lists widget fields and where to set them. Embed code should not include every key from the tables: most already have defaults. In kw('init'), keep only what differs from the default.

If the same field exists in the embed code and in Widget additional configuration on the Widget tab, the bot value wins after the chat connects.

Widget UI strings (input placeholder, header buttons): Widget UI strings.

Where to configure what

Bot Settings (Widget tab)

Labels match the UI.

One icon per bot. To tell a website and a PWA apart in the Operator Panel, use separate bots.

Steps: How to configure the widget in Settings, How to use Custom Code.

Appearance configuration page

Go to on the Widget tab. The panel does not store appearance as a separate bot preset: it builds the kw('init') object you copy onto the site.

In frame mode the constructor strips colors from the embed code.

Block texts: How to configure the IP blocking message.

What to put in kw('init')

The second argument is one object. An unknown key is ignored or stored if the name matches a widget field.

Live sites usually get the minimum or the configuration-page snippet. The full key map is in the catalog and the full object. Some branches apply only in a given mode (widgetButton for widget, multi_channel for type: "multi").

Minimum

kw('init', {
  bot_id: 1,
  language_code: "en"
});

Always set your bot_id. The site origin must already be in the list of allowed domains.

What the configuration page usually emits

The constructor adds what you changed in the panel. For a site button that is often (fields depend on the panel):

kw('init', {
  bot_id: 1,
  language_code: "en",
  displayMode: "widget",
  recognize_user_meta: true,
  open_on_msg: false,
  title: "Support",
  subtitle: "We are online",
  widgetButton: {
    type: "button",
    position: { y: "bottom", x: "right", offset: 25 }
  }
});

timeout_mode / timeout_value do not land in this object: the constructor writes setTimeout(function () { kw('init', { ... }); }, 3000) around the call.

Brand: title and colors

The most common manual edit after copying the snippet. Pass only the colors branches you change — the rest comes from the default theme.

kw('init', {
  bot_id: 1,
  language_code: "en",
  title: "Store",
  colors: {
    header: { bg: "#1A1A2E", text: "#ffffff" },
    launcher: { bg: "#1A1A2E" },
    sentMessage: { bg: "#1A1A2E", text: "#ffffff" },
    keyboardButton: { bg: "#1A1A2E", border: "#1A1A2E", text: "#ffffff" },
    inlineKeyboardButton: { bg: "#1A1A2E", text: "#1A1A2E", bgc: "#ffffff" }
  }
});

Step-by-step: How to customize widget colors. Branch map: Colors.

Add a key only when you need it

Do not merge these into one “universal” init.

Context for the scenario

params_from_site: {
  utm_source: "google",
  page_url: window.location.href
}

Custom JavaScript from the Widget tab — same host as the kwjs_v2.js script src:

widget_custom_code: true,
engine_url: "https://engine-instancename.connectiveone.io"

CMS removes the embed slot (floating displayMode: "widget" only):

move_to_body: true

Button with messengers — only if widgetButton.type is "multi":

widgetButton: { type: "multi" },
multi_channel: {
  button_title: "Contact us",
  messengers: {
    telegram: "https://t.me/your_bot",
    viber: "",
    facebook: "",
    whatsapp: "",
    instagram: ""
  }
}

UI strings — Widget UI strings:

custom_lang_translations: {
  en: {
    common: { write_a_message: "Type a message…" }
  }
}

Catalog of kw('init') keys

The Default column is what happens if you omit the key.

Always or almost always

Data for the scenario

Details: How to pass parameters from the website.

Window look and behavior

Button, launcher, multi-channel, callout

Pass the nested object as a whole or with the fields you change.

widgetButton — only for displayMode: "widget".

widgetButton: {
  type: "button", // button | bar | avatar | multi
  position: { y: "bottom", x: "right", offset: 25, offset_x: null, offset_y: null },
  currentPose: "stay", // for type: "avatar"
  scale: 11            // 6–18, for avatar
}

Top-level widget_button_animation: true — light animation for type: "button".

launcher — icon while the chat is collapsed.

launcher: {
  type: "icon", // or "image"
  closeIcon: "close",
  openIcon: "chat_bubble",
  staticImg: { src: "https://example.com/icon.png", fit: "unset" }
}

multi_channel — only with widgetButton.type: "multi". Otherwise the constructor drops this block.

callout — bubble next to the button before the chat opens.

callout: {
  type: "text", // or "image"
  text: "Need help?",
  show: true,
  showDelay: 1000,
  imgSrc: "",
  buttons: []
}

A scenario action widget__callout can also show a bubble during the dialog.

Colors (colors)

1. On the configuration page you pick a theme (primary, light, dark, persian_rose, pictorial_carmine, black). The embed gets an expanded colors object, not the theme name.
2. In kw('init') you can pass your own colors. The widget merges it with the default: change header.bg and the rest stays as in the theme.
3. At runtime: kw_event('kwcolor', { header: { bg: "#FF0000" } }).
4. frame mode: the constructor removes colors from the snippet. Set colors in init yourself if you still need them.

Values are CSS: #5B6BFF, rgb(), rgba(), linear-gradient(...), transparent.

Step-by-step: How to customize widget colors.

Look at an open chat with a corner button (displayMode: "widget").

device is barely visible with a normal site button. It matters when the device frame is on (hasDeviceFrame) or in the configuration-page preview.

Primary-theme defaults are in the full object. Constructor themes may also set border and dot on header / device.

Full kw('init') object

A map of every key the widget accepts in init. Values are examples, not a required production set. Do not paste this block wholesale onto a site. timeout_mode / timeout_value / v2_mode / preview_demo are not in this object: the constructor does not put them there.

kw('init', {
  bot_id: 1,
  user_id: "550e8400-e29b-41d4-a716-446655440000",
  language_code: "en",
  lang_available: ["uk", "en", "ru"],
  displayMode: "widget",
  hasDeviceFrame: false,
  move_to_body: false,
  open_on_msg: false,
  recognize_user_meta: true,
  widget_custom_code: false,
  engine_url: "https://engine-instancename.connectiveone.io",
  title: "👋 Hi!",
  subtitle: "",
  titleImageUrl: "https://example.com/logo.png",
  titleImageUrlSecond: null,
  botAvatarImageUrl: "https://example.com/avatar.png",
  avatar_online_marker: null,
  highlight_browser_tab_title: true,
  inline_keyboard_flex: false,
  minimize_to_avoid_chat_interrupt: true,
  privacy_policy_url: null,
  privacy_policy_is_mandatory: false,
  btn_restart_enabled: false,
  widget_button_animation: false,
  loadStateFromServerFirst: false,
  v2_value: null,
  params_from_site: {
    utm_source: "google",
    page_url: "https://shop.example.com/product/1",
    source_platform: "web",
    source_hostname: "shop.example.com"
  },
  user_block_message: {
    uk: "Доступ з цієї IP-адреси обмежено.",
    en: "Access from this IP address is restricted."
  },
  custom_lang_translations: {
    en: {
      common: { write_a_message: "Type a message…" }
    }
  },
  colors: {
    header: { bg: "#5B6BFF", text: "#ffffff", border: "#E4E4E4", dot: "#B8A6EE" },
    launcher: { bg: "#5B6BFF" },
    messageList: { bg: "#ffffff" },
    sentMessage: { bg: "#2A3F50", text: "#ffffff" },
    receivedMessage: { bg: "#E7EEF4", text: "#000000" },
    userInput: {
      bg: "#f4f7f9",
      border: "#f4f7f9",
      text: "#565867",
      icon_color: "#B3C0D2"
    },
    keyboardButton: { bg: "#33465B", border: "#33465B", text: "#FFFFFF" },
    inlineKeyboardButton: { bg: "#33465B", text: "#33465B", bgc: "#ffffff" },
    device: {
      bg: "#FCFCFC",
      dot: "#95CBFB",
      border: "#188BE4",
      container: "#FCFCFC"
    }
  },
  widgetButton: {
    type: "button",
    position: { y: "bottom", x: "right", offset: 25, offset_x: null, offset_y: null },
    currentPose: "stay",
    scale: 11
  },
  launcher: {
    type: "icon",
    closeIcon: "close",
    openIcon: "chat_bubble",
    staticImg: { src: "https://example.com/icon.png", fit: "unset" }
  },
  multi_channel: {
    button_title: "Contact us",
    messengers: {
      viber: "",
      telegram: "https://t.me/your_bot",
      facebook: "",
      whatsapp: "",
      instagram: ""
    }
  },
  callout: {
    type: "text",
    text: "Need help?",
    imgSrc: "",
    show: false,
    showDelay: 1000,
    minWidth: null,
    position: { x: "right", y: "bottom" },
    buttons: [],
    withTextRequest: false,
    withTextRequestParams: {}
  }
});

Limits

• One widget per page: #kwizbot_widget.
• Site origin must be in the list of allowed domains.
• HTTPS, except localhost.
• 10+ messages in 5 seconds blocks sending.
• Do not put constructor-only keys timeout_mode, timeout_value, v2_mode, preview_demo in init: in the generated snippet they are absent or become a wrapper, not widget fields.

Related articles

• What is the widget
• JavaScript API — events after launch (openchat, kwcolor, …)
• Widget UI strings
• How to configure the widget in Settings
• How to connect the widget to a website
• How to pass parameters from the website
• How to customize colors
• How to use Custom Code