---
title: "Widget settings parameters"
description: "Widget field reference: Widget tab, appearance page, kw('init') keys, colors, and nested objects."
---

# 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](/en/channels/how-to/widget/widget-ui-texts.md).

## Where to configure what

| Place | What it covers |
|---|---|
| **Menu → Settings → Bots → select a bot → Widget** | Allowed origins, extra JSON, Operator Panel channel icon, custom JavaScript |
| **Scenario Builder → start step → Widget channel** | The same origins, icon, and JSON. Labels differ; stored values are shared |
| **Widget configuration page** (**Go to**) | Appearance. Copy a ready `kw('init')` from here |
| Site code `kw('init', { ... })` | Launch on the page. You can add keys that are not in the form |

---

## Bot Settings (Widget tab)

Labels match the UI.

| UI field | What it does | Required |
|---|---|---|
| **List of allowed domains for installing the widget** | Site origin: `https://www.example.com` — with protocol, no trailing slash, no path | Yes. Otherwise chat from the site will not connect |
| **Widget additional configuration** | JSON merged into widget state after connect. Empty is fine | No. Invalid JSON may not apply |
| **widget badge_url** | Channel icon URL in the Operator Panel chat list | No |
| **Custom Widget JavaScript Code** | Runs on the site while the widget loads. Button **Open JavaScript Editor** | No. `init` also needs `widget_custom_code: true` and `engine_url` |
| **Widget configuration page → Go to** | Appearance constructor and embed code | — |
| Previous widget version | Legacy embeds. No longer supported | Do not use for new sites |
| **Save config** | Writes origins, JSON, icon, and custom code | Disabled while any origin in the list is invalid |

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](/en/channels/how-to/widget/configure-widget-settings.md), [How to use Custom Code](/en/channels/how-to/widget/use-widget-custom-code.md).

---

## 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.

| Control in the panel | What appears in the code |
|---|---|
| Bot ID | `bot_id` |
| Language | `language_code` |
| Show after delay | Not an `init` key. A `setTimeout(...)` wrapper around the call |
| Collect visitor data | `recognize_user_meta` |
| Mode: button / fill container / embedded | `displayMode`: `widget` \| `frame` \| `inline` |
| Theme (primary, light, dark, …) | A full `colors` object. The theme **name** is not in `init` |
| Title, subtitle, images | `title`, `subtitle`, `titleImageUrl`, `botAvatarImageUrl` |
| Button type, launcher, avatar, multi-channel, callout | `widgetButton`, `launcher`, `multi_channel`, `callout` |
| Text when an IP is blocked | `user_block_message` |

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

Block texts: [How to configure the IP blocking message](/en/channels/how-to/widget/configure-ip-blocking-message.md).

---

## 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](#catalog-of-kwinit-keys) and the [full object](#full-kwinit-object). Some branches apply only in a given mode (`widgetButton` for `widget`, `multi_channel` for `type: "multi"`).

### Minimum

```javascript
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):

```javascript
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.

```javascript
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](/en/channels/how-to/widget/customize-widget-colors.md). Branch map: [Colors](#colors-colors).

### Add a key only when you need it

Do not merge these into one “universal” init.

**Context for the scenario**

```javascript
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`:

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

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

```javascript
move_to_body: true
```

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

```javascript
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](/en/channels/how-to/widget/widget-ui-texts.md):

```javascript
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

| Key | Type | Default | Why |
|---|---|---|---|
| `bot_id` | number | widget build default (samples often use `1`) | Always your bot |
| `language_code` | string | browser language | Widget UI language: `uk`, `en`, `ru`, … |
| `displayMode` | string | `widget` | `widget` — button; `frame` — fills the container (account, WebView); `inline` — block in the page |
| `user_id` | string | UUID in a cookie ~30 days | Same visitor = same chat |

### Data for the scenario

| Key | Type | Default | Why |
|---|---|---|---|
| `params_from_site` | object | `{}` | Your fields. In the scenario: `{{key_name}}` |
| `recognize_user_meta` | boolean | `true` | `false` — do not add IP, user agent, platform, and page host |
| `params_from_site.source_platform` | string | `web` / `ios` / `android` automatically | Your value is stored in Statistics |
| `params_from_site.source_hostname` | string | page host | Same for the source site |

Details: [How to pass parameters from the website](/en/channels/how-to/widget/pass-parameters-from-widget.md).

### Window look and behavior

| Key | Type | Default | Why |
|---|---|---|---|
| `title` / `subtitle` | string | `👋 Hi!` / empty | Chat header |
| `titleImageUrl` | URL | default | Header logo |
| `titleImageUrlSecond` | URL or `null` | `null` | Second header image |
| `botAvatarImageUrl` | URL | default | Bot avatar in the thread |
| `colors` | object | primary theme, [below](#colors-colors) | Brand |
| `open_on_msg` | boolean | `false` in constructor code | Open the window when a message arrives, even if collapsed |
| `move_to_body` | boolean | `false` | Floating widget when the CMS wipes `#kwizbot_widget`. Not for `inline` or `frame` |
| `highlight_browser_tab_title` | boolean | `true` | Flash the browser tab title on a new message |
| `privacy_policy_url` | URL or `null` | `null` | Privacy policy link in the header |
| `privacy_policy_is_mandatory` | boolean | `false` | Block typing until consent |
| `hasDeviceFrame` | boolean | `false` | Device bezel |
| `inline_keyboard_flex` | boolean | `false` | Stretch inline buttons |
| `minimize_to_avoid_chat_interrupt` | boolean | `true` | Collapse so the widget covers less of the page |
| `btn_restart_enabled` | boolean | `false` | Restart-dialog control |
| `user_block_message` | object | `{}` | `{ uk: "…", en: "…" }` when the IP is blocked |
| `lang_available` | string[] | `en`, `uk`, `ru` | Allowed languages |
| `custom_lang_translations` | object | `{}` | Override UI strings. Keys — [Widget UI strings](/en/channels/how-to/widget/widget-ui-texts.md) |
| `widget_custom_code` | boolean | `false` | Run **Custom Widget JavaScript Code** |
| `engine_url` | string | — | Together with `widget_custom_code: true` |
| `loadStateFromServerFirst` | boolean | `false` | Load history from the server first |
| `avatar_online_marker` | any | `null` | Online marker next to the avatar |
| `v2_value` | string | — | Internal, from the configuration page URL. Do not set by hand |

### Button, launcher, multi-channel, callout

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

**`widgetButton`** — only for `displayMode: "widget"`.

```javascript
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.

```javascript
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.

```javascript
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](/en/channels/how-to/widget/customize-widget-colors.md).

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

| What the visitor sees | `colors` branch | Fields |
|---|---|---|
| Button / disc while the chat is collapsed | `launcher` | `bg` — button background |
| Top bar of the open window (title) | `header` | `bg` background, `text` text, `border` line, `dot` indicator |
| Message list background | `messageList` | `bg` |
| **Visitor** bubble | `sentMessage` | `bg`, `text` |
| **Bot or operator** bubble | `receivedMessage` | `bg`, `text` |
| “Write a message” field | `userInput` | `bg`, `text`, `border`, `icon_color` |
| Reply buttons under a message (scenario keyboard) | `keyboardButton` | `bg`, `border`, `text` |
| Inline buttons in a message | `inlineKeyboardButton` | `bg`, `text`, `bgc` (hover background) |
| Decorative device bezel (if enabled) | `device` | `container`, `bg`, `border`, `dot` |

`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](#full-kwinit-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.

```javascript
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](/en/channels/explanation/what-is-widget.md)
- [JavaScript API](/en/channels/explanation/widget-javascript-api.md) — events after launch (`openchat`, `kwcolor`, …)
- [Widget UI strings](/en/channels/how-to/widget/widget-ui-texts.md)
- [How to configure the widget in Settings](/en/channels/how-to/widget/configure-widget-settings.md)
- [How to connect the widget to a website](/en/channels/how-to/widget/setup-widget-on-website.md)
- [How to pass parameters from the website](/en/channels/how-to/widget/pass-parameters-from-widget.md)
- [How to customize colors](/en/channels/how-to/widget/customize-widget-colors.md)
- [How to use Custom Code](/en/channels/how-to/widget/use-widget-custom-code.md)