# 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` розміщення

**Приклад:**
```javascript
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)`** — закрити чат

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

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

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

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

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

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

**Приклад:**
```javascript
kw_event('emitevent', {
  event: 'alias',
  alias: 'product-inquiry'
});
```

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

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

**Приклад:**
```javascript
kw_event('kwsetparamsfromsite', {
  params_from_site: {
    company_name: 'TV123123',
    page_url: window.location.href
  }
});
```

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

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

**Приклад:**
```javascript
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` — змінити заголовок

**Приклад:**
```javascript
// Створення нового чату
kw_event('kwreinitwidget', { user_id: null });

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

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

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

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

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

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

Після виконання в `localStorage` зберігається:
- `isChatOpen` — стан віджета (згорнутий/розгорнутий)
- `connectState` — стан підключення оператора

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

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

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

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

**Приклад:**
```javascript
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:**
```javascript
// Модифікація параметрів перед ініціалізацією
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 секунд

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

- [Що таке віджет](/uk/channels/explanation/what-is-widget.md)
- [Підключення віджету на сайт](/uk/channels/how-to/setup-widget-on-website.md)
- [Передача параметрів з сайту до сценарію](/uk/channels/how-to/pass-parameters-from-widget.md)
- [Керування віджетом з сайту](/uk/channels/how-to/manage-widget-from-site.md)
- [Робота з SPA додатками](/uk/channels/how-to/work-with-widget-spa.md)
- [Використання Custom Code](/uk/channels/how-to/use-widget-custom-code.md)
- [Обмін даними з виджетом](/uk/integrations/explanation/what-are-integrations.md#обмін-даними-з-виджетом)