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

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

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

Підписи інтерфейсу віджета (поле вводу, кнопки шапки): Тексти інтерфейсу віджета.

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

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

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

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

Кроки: Як налаштувати віджет у Налаштуваннях, Як використовувати Custom Code.

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

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

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

Тексти блокування: Як налаштувати повідомлення про блокування за IP-адресою.

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

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

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

Мінімум

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

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

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

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

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, які змінюєте — решта візьметься з типової теми.

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" }
  }
});

Покроково: Як кастомізувати кольори віджету. Карта гілок — Кольори.

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

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

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

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

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

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

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

move_to_body: true

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

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

Підписи інтерфейсу — Тексти інтерфейсу віджета:

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

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

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

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

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

Деталі: Як передати параметри з сайту до сценарію.

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

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

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

widgetButton — лише для displayMode: "widget".

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 — іконка згорнутого чату.

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

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

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

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.

Покроково: Як кастомізувати кольори віджету.

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

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

Типові значення теми primary — у повному об’єкті. У готових темах конструктора в header / device можуть з’явитися ще border і dot.

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

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

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: у готовому коді їх або немає, або вони стають обгорткою, а не полями віджета.

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

• Що таке віджет
• JavaScript API — події після запуску (openchat, kwcolor, …)
• Тексти інтерфейсу віджета
• Як налаштувати віджет у Налаштуваннях
• Як підключити віджет на сайт
• Як передати параметри з сайту
• Як кастомізувати кольори
• Як використовувати Custom Code