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

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

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

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

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

Параметри:

  • bot_id — ідентифікатор бота (за замовчуванням 1)
  • user_id — ідентифікатор користувача (опціонально, генерується автоматично)
  • language_code — мова інтерфейсу (uk, ru, en тощо)
  • params_from_site — додаткові параметри для сценарію
  • color — кольорова схема віджету
  • open_on_msg — автоматично відкривати чат при отриманні повідомлення
  • recognize_user_meta — відображати IP, місто, країну в операторській панелі

Приклад:

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 секунд

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