---
title: "Параметри налаштувань віджета"
description: "Довідник полів віджета: вкладка Widget, сторінка вигляду, ключі kw('init'), colors і вкладені об’єкти."
---

# Параметри налаштувань віджета

На цій сторінці — поля віджета й те, **куди їх писати**. Код вставки не повинен містити всі ключі з таблиць: більшість уже має типове значення. У `kw('init')` лишайте те, що відрізняється від типового.

Якщо те саме поле є і в коді вставки, і в **Додатковій конфігурації віджета** на вкладці Widget, після підключення чату перемагає значення з бота.

Підписи інтерфейсу віджета (поле вводу, кнопки шапки): [Тексти інтерфейсу віджета](/uk/channels/how-to/widget/widget-ui-texts.md).

## Де що налаштовується

| Місце | Що тут |
|---|---|
| **Меню → Налаштування → Боти → оберіть бота → Widget** | Дозволені домени, додатковий JSON, іконка каналу в Операторській панелі, власний JavaScript |
| **Конструктор сценаріїв → стартовий крок → канал Widget** | Ті самі домени, іконка й JSON. Підписи полів інші, значення спільні |
| **Сторінка конфігурації віджету** (кнопка **Перейти**) | Вигляд. Звідси копіюєте готовий `kw('init')` |
| Код на сайті `kw('init', { ... })` | Запуск на сторінці. Сюди ж можна дописати ключі, яких немає в формі |

---

## Налаштування бота (вкладка Widget)

Підписи — як у інтерфейсі.

| Поле в інтерфейсі | Що робить | Обов’язкове |
|---|---|---|
| **Список дозволених доменів для встановлення віджету** | Origin сайту: `https://www.example.com` — з протоколом, без слеша в кінці, без шляху | Так. Інакше чат з сайту не підключиться |
| **Додаткова конфігурація віджета** | JSON, який після підключення накладається на стан віджета. Можна залишити порожнім | Ні. Некоректний JSON може не застосуватися |
| **widget badge_url** | URL іконки каналу в списку чатів Операторської панелі | Ні |
| **Власний JavaScript-код віджета** | Код на сайті під час завантаження. Кнопка **Відкрити редактор JavaScript** | Ні. У `init` ще потрібні `widget_custom_code: true` і `engine_url` |
| **Сторінка конфігурації віджету → Перейти** | Конструктор вигляду й код вставки | — |
| Попередня версія віджету | Старі інтеграції. Більше не підтримується | Не для нових сайтів |
| **Зберегти конфіг** | Записує домени, JSON, іконку й власний код | Неактивна, поки в списку доменів є помилка |

Одна іконка на одного бота. Щоб відрізнити сайт і PWA в Операторській панелі — окремі боти.

Кроки: [Як налаштувати віджет у Налаштуваннях](/uk/channels/how-to/widget/configure-widget-settings.md), [Як використовувати Custom Code](/uk/channels/how-to/widget/use-widget-custom-code.md).

---

## Сторінка конфігурації вигляду

Кнопка **Перейти** на вкладці Widget. Панель не зберігає вигляд «у боті як окремий пресет»: вона **збирає об’єкт для `kw('init')`**, який ви копіюєте на сайт.

| Що крутите в панелі | Що з’являється в коді |
|---|---|
| Ідентифікатор бота | `bot_id` |
| Мова | `language_code` |
| Затримка появи | Не ключ `init`. Обгортка `setTimeout(...)` навколо виклику |
| Збирати дані про відвідувача | `recognize_user_meta` |
| Режим: кнопка / на весь блок / вбудований | `displayMode`: `widget` \| `frame` \| `inline` |
| Тема (primary, light, dark, …) | Готовий об’єкт `colors`. Імені теми в `init` немає |
| Заголовок, підзаголовок, картинки | `title`, `subtitle`, `titleImageUrl`, `botAvatarImageUrl` |
| Тип кнопки, лаунчер, аватар, мультиканал, callout | `widgetButton`, `launcher`, `multi_channel`, `callout` |
| Текст, коли IP заблоковано | `user_block_message` |

У режимі `frame` конструктор **викидає `colors`** з коду вставки.

Тексти блокування: [Як налаштувати повідомлення про блокування за IP-адресою](/uk/channels/how-to/widget/configure-ip-blocking-message.md).

---

## Що класти в `kw('init')`

Другий аргумент — один об’єкт. Невідомий ключ або ігнорується, або потрапляє в стан, якщо ім’я збігається з полем віджета.

На сайт зазвичай іде **мінімум** або фрагмент зі сторінки конфігурації. Повна карта ключів — у [каталозі](#каталог-ключів-kwinit) і [повному об’єкті](#повний-обєкт-kwinit). Частина гілок має сенс лише в певному режимі (`widgetButton` — для `widget`, `multi_channel` — для `type: "multi"`).

### Мінімум

```javascript
kw('init', {
  bot_id: 1,
  language_code: "uk"
});
```

Завжди ставте свій `bot_id`. Origin сайту вже має бути в **Списку дозволених доменів**.

### Як зазвичай виглядає код зі сторінки конфігурації

Конструктор додає те, що ви змінили в панелі. Для кнопки на сайті це часто таке (набір полів залежить від панелі):

```javascript
kw('init', {
  bot_id: 1,
  language_code: "uk",
  displayMode: "widget",
  recognize_user_meta: true,
  open_on_msg: false,
  title: "Підтримка",
  subtitle: "Ми онлайн",
  widgetButton: {
    type: "button",
    position: { y: "bottom", x: "right", offset: 25 }
  }
});
```

`timeout_mode` / `timeout_value` в цей об’єкт **не потрапляють**: конструктор пише `setTimeout(function () { kw('init', { ... }); }, 3000)` навколо виклику.

### Бренд: заголовок і кольори

Найчастіша ручна доробка після копіювання коду. Достатньо передати **ті гілки `colors`, які змінюєте** — решта візьметься з типової теми.

```javascript
kw('init', {
  bot_id: 1,
  language_code: "uk",
  title: "Магазин",
  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" }
  }
});
```

Покроково: [Як кастомізувати кольори віджету](/uk/channels/how-to/widget/customize-widget-colors.md). Карта гілок — [Кольори](#кольори-colors).

### Коли потрібен окремий фрагмент

Дописуйте ключ, лише якщо задача є. Не збирайте їх в один «універсальний» init.

**Контекст для сценарію**

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

**Власний JavaScript з вкладки Widget** — адреса та сама, що в `src` скрипта `kwjs_v2.js`:

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

**CMS з’їдає блок вставки** (лише плаваючий `displayMode: "widget"`):

```javascript
move_to_body: true
```

**Кнопка з месенджерами** — лише якщо `widgetButton.type` = `"multi"`:

```javascript
widgetButton: { type: "multi" },
multi_channel: {
  button_title: "Написати нам",
  messengers: {
    telegram: "https://t.me/your_bot",
    viber: "",
    facebook: "",
    whatsapp: "",
    instagram: ""
  }
}
```

**Підписи інтерфейсу** — [Тексти інтерфейсу віджета](/uk/channels/how-to/widget/widget-ui-texts.md):

```javascript
custom_lang_translations: {
  uk: {
    common: { write_a_message: "Напишіть нам…" }
  }
}
```

---

## Каталог ключів `kw('init')`

Колонка «Типово» — що буде, якщо ключ **не** передавати.

### Завжди або майже завжди

| Ключ | Тип | Типово | Навіщо |
|---|---|---|---|
| `bot_id` | number | значення збірки віджета (у прикладах часто `1`) | Обов’язково свій бот |
| `language_code` | string | мова браузера | Мова підписів віджета: `uk`, `en`, `ru`, … |
| `displayMode` | string | `widget` | `widget` — кнопка; `frame` — на весь контейнер (кабінет, WebView); `inline` — блок у сторінці |
| `user_id` | string | UUID у cookie ~30 днів | Той самий відвідувач = той самий чат |

### Дані для сценарію

| Ключ | Тип | Типово | Навіщо |
|---|---|---|---|
| `params_from_site` | object | `{}` | Свої поля. У сценарії `{{ім_я_ключа}}` |
| `recognize_user_meta` | boolean | `true` | `false` — не додавати IP, рядок браузера, платформу й домен сторінки |
| `params_from_site.source_platform` | string | `web` / `ios` / `android` автоматично | Своє значення піде в статистику |
| `params_from_site.source_hostname` | string | домен сторінки | Те саме для сайту-джерела |

Деталі: [Як передати параметри з сайту до сценарію](/uk/channels/how-to/widget/pass-parameters-from-widget.md).

### Вигляд і поведінка вікна

| Ключ | Тип | Типово | Навіщо |
|---|---|---|---|
| `title` / `subtitle` | string | `👋 Hi!` / порожньо | Шапка чату |
| `titleImageUrl` | URL | стандартне | Логотип у шапці |
| `titleImageUrlSecond` | URL або `null` | `null` | Друге зображення в шапці |
| `botAvatarImageUrl` | URL | стандартне | Аватар бота в стрічці |
| `colors` | object | тема primary, [нижче](#кольори-colors) | Бренд |
| `open_on_msg` | boolean | `false` у коді конструктора | Відкрити вікно, коли прийшло повідомлення, навіть якщо згорнуто |
| `move_to_body` | boolean | `false` | Плаваючий віджет, якщо CMS зтирає `#kwizbot_widget`. Не для `inline` і `frame` |
| `highlight_browser_tab_title` | boolean | `true` | Миготіння заголовка вкладки при новому повідомленні |
| `privacy_policy_url` | URL або `null` | `null` | Посилання на політику в шапці |
| `privacy_policy_is_mandatory` | boolean | `false` | Не писати в чат, доки немає згоди |
| `hasDeviceFrame` | boolean | `false` | Рамка «пристрою» |
| `inline_keyboard_flex` | boolean | `false` | Розтягнути inline-кнопки |
| `minimize_to_avoid_chat_interrupt` | boolean | `true` | Згортати вікно, щоб менше крити сторінку |
| `btn_restart_enabled` | boolean | `false` | Кнопка перезапуску діалогу |
| `user_block_message` | object | `{}` | `{ uk: "…", en: "…" }` коли IP заблоковано |
| `lang_available` | string[] | `en`, `uk`, `ru` | Які мови дозволені |
| `custom_lang_translations` | object | `{}` | Підмінити рядки UI. Ключі — [Тексти інтерфейсу віджета](/uk/channels/how-to/widget/widget-ui-texts.md) |
| `widget_custom_code` | boolean | `false` | Виконати **Власний JavaScript-код віджета** |
| `engine_url` | string | — | Разом із `widget_custom_code: true` |
| `loadStateFromServerFirst` | boolean | `false` | Спочатку історія з сервера |
| `avatar_online_marker` | будь-що | `null` | Маркер «онлайн» біля аватара |
| `v2_value` | string | — | Службове з URL сторінки конфігурації. Не ставте вручну |

### Кнопка, лаунчер, мультиканал, callout

Передавайте вкладений об’єкт цілком або з тими полями, які змінюєте.

**`widgetButton`** — лише для `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", // для type: "avatar"
  scale: 11            // 6–18, для avatar
}
```

Окремий ключ верхнього рівня `widget_button_animation: true` — легка анімація для `type: "button"`.

**`launcher`** — іконка згорнутого чату.

```javascript
launcher: {
  type: "icon", // або "image"
  closeIcon: "close",
  openIcon: "chat_bubble",
  staticImg: { src: "https://example.com/icon.png", fit: "unset" }
}
```

**`multi_channel`** — лише з `widgetButton.type: "multi"`. Інакше конструктор викидає цей блок.

**`callout`** — хмарка біля кнопки до відкриття чату.

```javascript
callout: {
  type: "text", // або "image"
  text: "Потрібна допомога?",
  show: true,
  showDelay: 1000,
  imgSrc: "",
  buttons: []
}
```

Підказку під час діалогу може показати дія сценарію `widget__callout`.

---

## Кольори (`colors`)

1. На сторінці конфігурації ви обираєте **тему** (primary, light, dark, persian_rose, pictorial_carmine, black). У код іде не назва теми, а вже розгорнутий об’єкт `colors`.
2. У `kw('init')` можна передати свій `colors`. Віджет **зливає** його з типовим: змінюєте `header.bg` — решта лишається як у темі.
3. Під час роботи: `kw_event('kwcolor', { header: { bg: "#FF0000" } })`.
4. Режим `frame`: конструктор прибирає `colors` з коду. Для frame задавайте кольори вручну в `init`, якщо вони потрібні.

Значення — CSS: `#5B6BFF`, `rgb()`, `rgba()`, `linear-gradient(...)`, `transparent`.

Покроково: [Як кастомізувати кольори віджету](/uk/channels/how-to/widget/customize-widget-colors.md).

Дивіться на відкритий чат з кнопкою в куті (`displayMode: "widget"`).

| Що бачить відвідувач | Гілка `colors` | Поля |
|---|---|---|
| Кнопка / кружок, поки чат згорнутий | `launcher` | `bg` — фон кнопки |
| Смуга зверху відкритого вікна (заголовок) | `header` | `bg` фон, `text` текст, `border` лінія, `dot` індикатор |
| Фон стрічки повідомлень | `messageList` | `bg` |
| Бульбашка **відвідувача** | `sentMessage` | `bg`, `text` |
| Бульбашка **бота або оператора** | `receivedMessage` | `bg`, `text` |
| Поле «напишіть повідомлення» | `userInput` | `bg`, `text`, `border`, `icon_color` |
| Кнопки відповіді під повідомленням (клавіатура сценарію) | `keyboardButton` | `bg`, `border`, `text` |
| Кнопки в рядок у повідомленні | `inlineKeyboardButton` | `bg`, `text`, `bgc` (фон у стані наведення) |
| Декоративна рамка «пристрою» (якщо увімкнена) | `device` | `container`, `bg`, `border`, `dot` |

`device` майже не видно в звичайній кнопці на сайті. Він потрібен, коли є рамка пристрою (`hasDeviceFrame`) або прев’ю на сторінці конфігурації.

Типові значення теми primary — у [повному об’єкті](#повний-обєкт-kwinit). У готових темах конструктора в `header` / `device` можуть з’явитися ще `border` і `dot`.

---

## Повний об’єкт `kw('init')`

Карта всіх ключів, які віджет приймає в `init`. Значення — приклад, не обов’язковий прод-набір. Не вставляйте цей блок цілком на сайт. `timeout_mode` / `timeout_value` / `v2_mode` / `preview_demo` сюди не входять: конструктор їх не кладе в об’єкт.

```javascript
kw('init', {
  bot_id: 1,
  user_id: "550e8400-e29b-41d4-a716-446655440000",
  language_code: "uk",
  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: {
    uk: {
      common: { write_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: "Написати нам",
    messengers: {
      viber: "",
      telegram: "https://t.me/your_bot",
      facebook: "",
      whatsapp: "",
      instagram: ""
    }
  },
  callout: {
    type: "text",
    text: "Потрібна допомога?",
    imgSrc: "",
    show: false,
    showDelay: 1000,
    minWidth: null,
    position: { x: "right", y: "bottom" },
    buttons: [],
    withTextRequest: false,
    withTextRequestParams: {}
  }
});
```

---

## Обмеження

- Один віджет на сторінку: елемент `#kwizbot_widget`.
- Origin сайту — у **Списку дозволених доменів**.
- HTTPS, окрім `localhost`.
- 10+ повідомлень за 5 секунд — відправлення блокується.
- Не кладіть у `init` службові ключі конструктора `timeout_mode`, `timeout_value`, `v2_mode`, `preview_demo`: у готовому коді їх або немає, або вони стають обгорткою, а не полями віджета.

## Пов’язані статті

- [Що таке віджет](/uk/channels/explanation/what-is-widget.md)
- [JavaScript API](/uk/channels/explanation/widget-javascript-api.md) — події після запуску (`openchat`, `kwcolor`, …)
- [Тексти інтерфейсу віджета](/uk/channels/how-to/widget/widget-ui-texts.md)
- [Як налаштувати віджет у Налаштуваннях](/uk/channels/how-to/widget/configure-widget-settings.md)
- [Як підключити віджет на сайт](/uk/channels/how-to/widget/setup-widget-on-website.md)
- [Як передати параметри з сайту](/uk/channels/how-to/widget/pass-parameters-from-widget.md)
- [Як кастомізувати кольори](/uk/channels/how-to/widget/customize-widget-colors.md)
- [Як використовувати Custom Code](/uk/channels/how-to/widget/use-widget-custom-code.md)