JavaScript API для керування віджетом

ConnectiveOne віджет надає JavaScript API для керування поведінкою віджету з вашого сайту. Це дозволяє програмно відкривати/закривати чат, змінювати параметри, передавати події до сценарію та інтегрувати віджет з SPA додатками.

Основні функції

Ініціалізація віджету

kw('init', {...}) — ініціалізує віджет з параметрами.

Параметри:

• bot_id — ідентифікатор бота (за замовчуванням 1)
• user_id — ідентифікатор користувача (опціонально, генерується автоматично)
• language_code — мова інтерфейсу (uk, ru, en тощо)
• params_from_site — додаткові параметри для сценарію
• colors — кольорова схема віджету
• open_on_msg — автоматично відкривати чат при отриманні повідомлення
• recognize_user_meta — збір даних про клієнта для операторської панелі та статистики: за замовчуванням увімкнено (true). Додаються IP-адреса, user agent, автоматично визначена платформа (source_platform) і домен сторінки вбудовування (source_hostname). Встановіть false, щоб вимкнути
• move_to_body — опціональний прапорець стабільності для floating widget mode. За замовчуванням: false. Якщо встановити true, віджет переносить свій змонтований root у document.body і видаляє порожні дублікати #kwizbot_widget, які створює сторінка. Не використовуйте для inline або frame розміщення

Приклад:

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

Керування чатом

kw_event('openchat', 1) — відкрити чат

kw_event('openchat', 0) — закрити чат

Приклад:

// Відкрити чат при кліку на кнопку
document.getElementById('open-chat-btn').addEventListener('click', function() {
  kw_event('openchat', 1);
});

Зміна заголовка та підзаголовка

kw_event('command', { title: '...', subtitle: '...' }) — змінити заголовок та підзаголовок чату

Приклад:

kw_event('command', {
  title: "Новий заголовок",
  subtitle: "Новий підзаголовок"
});

Перехід до точки входу в сценарій

kw_event('emitevent', { event: 'alias', alias: 'test-alias' }) — перейти до вказаного alias в сценарії

Приклад:

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

Передача параметрів з сайту

kw_event('kwsetparamsfromsite', { params_from_site: {...} }) — змінити параметри під час роботи

Приклад:

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

Зміна кольорів

kw_event('kwcolor', { header: { bg: '#FF0000' } }) — змінити кольори віджету

Приклад:

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

Робота з SPA

kw_event('kwreinitwidget', {...}) — переініціалізувати віджет (для SPA)

Параметри:

• user_id — змінити користувача (або null для нового чату)
• params_from_site — оновити параметри
• title, subtitle — змінити заголовок

Приклад:

// Створення нового чату
kw_event('kwreinitwidget', { user_id: null });

// Зміна параметрів
kw_event('kwreinitwidget', {
  params_from_site: { type: 'mobile' }
});

kw_event('kwvisiblelauncher', { visible: false }) — сховати/показати лаунчер

Приклад:

// Сховати лаунчер
kw_event('kwvisiblelauncher', { visible: false });

// Показати лаунчер
kw_event('kwvisiblelauncher', { visible: true });

Збереження стану

kw_event('widgetstatus', 1) — зберегти стан чату в localStorage

Після виконання в localStorage зберігається:

• isChatOpen — стан віджета (згорнутий/розгорнутий)
• connectState — стан підключення оператора

Події віджету

Ви можете слухати події віджету:

widgetChatOpened — чат відкрито

widgetChatClosed — чат закрито

Приклад:

document.addEventListener("widgetChatOpened", function(event) {
  console.log('Чат відкрито', event);
  // Ваш код обробки
});

document.addEventListener("widgetChatClosed", function(event) {
  console.log('Чат закрито', event);
  // Ваш код обробки
});

Custom Code

Ви можете додати кастомний JavaScript код, який виконується перед ініціалізацією віджету. Код має доступ до:

• embed_state — стан віджету перед ініціалізацією
• kw_event() — функція для виклику подій
• kw_event_trigger() — функція для тригеру подій

Де налаштувати: Налаштування → Боти → оберіть бота → Widget → Custom Code

Приклад Custom Code:

// Модифікація параметрів перед ініціалізацією
embed_state.params_from_site = {
  ...embed_state.params_from_site,
  page_url: window.location.href,
  user_agent: navigator.userAgent
};

// Інтеграція з Google Analytics
if (window.gtag) {
  window.addEventListener('widgetChatOpened', function() {
    window.gtag('event', 'widget_chat_opened');
  });
}

Обмеження

• На одній сторінці може бути лише один екземпляр віджету
• Віджет працює тільки через HTTPS (крім localhost)
• Домени для віджету повинні бути додані в CORS settings
• Захист від спаму: автоматичне блокування при 10+ повідомленнях за 5 секунд

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

• Що таке віджет
• Підключення віджету на сайт
• Передача параметрів з сайту до сценарію
• Керування віджетом з сайту
• Робота з SPA додатками
• Використання Custom Code
• Обмін даними з виджетом