# Що таке інтеграції ConnectiveOne

Інтеграції дозволяють з'єднати ConnectiveOne з вашими зовнішніми системами (CRM, ERP, маркетингові платформи, власні застосунки) для обміну даними та автоматизації процесів.

## Навіщо потрібні інтеграції?

Інтеграції допомагають:

- **Автоматизувати процеси** — запускати сценарії ботів з ваших систем
- **Синхронізувати дані** — обмінюватися інформацією між ConnectiveOne та іншими системами
- **Отримувати події** — відстежувати зміни в операторській панелі та діалогах
- **Розширювати функціональність** — підключати додаткові канали та сервіси

## Типи інтеграцій

ConnectiveOne підтримує кілька типів інтеграцій, кожен з яких вирішує свої завдання.

### Custom Channel

**Що це:** Інтеграція зовнішніх систем через HTTP POST запити. Custom Channel дозволяє підключити будь-яку систему, яка може відправляти та приймати HTTP запити.

**Коли використовувати:**
- Потрібно підключити існуючий бот з іншої системи до ConnectiveOne
- Потрібно інтегрувати переписку з CRM до ConnectiveOne
- Потрібно швидко підключити новий канал (месенджер), для якого ще немає офіційної інтеграції
- Потрібна повноцінна двостороння інтеграція (відправка та отримання повідомлень)

**Як працює:**
- Ваша система відправляє POST запити на `input_url` ConnectiveOne
- ConnectiveOne відправляє повідомлення та події на ваш `custom_channel_url`
- Всі повідомлення та події обробляються через сценарії ConnectiveOne

**Детальніше:** → [Інтеграція через Custom Channel](/uk/integrations/how-to/custom-channel/integrate-via-custom-channel.md)

---

### API (Enterprise API, Public API)

**Що це:** REST API для отримання та зміни даних ConnectiveOne. Дозволяє читати та змінювати інформацію про діалоги, операторів, користувачів, тікети та інші об'єкти.

**Коли використовувати:**
- Потрібно отримати дані про діалоги, операторів, користувачів з ConnectiveOne
- Потрібно змінити параметри діалогу (статус, тему, коментар) з зовнішньої системи
- Потрібно синхронізувати дані між ConnectiveOne та вашою системою
- Потрібно інтегрувати ConnectiveOne з вашою CRM/ERP системою

**Як працює:**
- Ви відправляєте HTTP запити (GET, POST) на endpoints ConnectiveOne
- Використовуєте API ключ або JWT токен для авторизації
- Отримуєте дані у форматі JSON

**Детальніше:**
- → [Використання API](/uk/integrations/how-to/use-api.md)
- → [API довідник](/uk/integrations/reference/api-reference.md)

---

### call_node (Call Node API)

**Що це:** API для запуску сценаріїв ботів з зовнішніх систем. Дозволяє викликати будь-яку точку входу (Entry Point) в сценарії та передати параметри.

**Коли використовувати:**
- Потрібно відправити повідомлення клієнту про статус замовлення/доставки
- Потрібно запустити опитування задоволеності після надання послуги
- Потрібно надіслати нагадування про необхідність оплати
- Потрібно запустити інтеграційний процес (наприклад, синхронізація довідників)

**Як працює:**
- Ви відправляєте POST запит на endpoint `/kw/api/call_node/` або використовуєте Entry Point URL
- Вказуєте `bot_id`, `connector_alias` (точку входу), `chat_id`, `channel`
- Можете передати додаткові параметри в `data`, які будуть доступні в сценарії
- ConnectiveOne запускає сценарій для вказаного користувача

**Детальніше:** → [Запуск сценарію через API call_node](/uk/integrations/how-to/launch-scenario-via-call-node.md)

---

### Webhooks операторської панелі

**Що це:** Механізм отримання подій з операторської панелі на ваш зовнішній сервіс. Webhook відправляє події (створення чату, підключення оператора, закриття чату) на вказаний URL.

**Коли використовувати:**
- Потрібно відстежувати події в операторській панелі (створення чату, підключення оператора)
- Потрібно синхронізувати статуси діалогів з вашою CRM системою
- Потрібно логувати події операторської панелі в зовнішню систему
- Потрібно інтегрувати з системою аналітики

**Як працює:**
- Ви вказуєте `event_webhook_url` в action `operator_panel__connect_to_operator_with_msg`
- ConnectiveOne відправляє POST запити з подіями на ваш URL
- Ваш сервіс обробляє події та виконує необхідні дії

**Відмінності від Custom Channel:**
- Webhook панелі оператора відправляє тільки події з операторської панелі
- Не потребує окремого налаштування каналу
- Налаштовується безпосередньо в action

**Детальніше:** → [Налаштування webhook панелі оператора](/uk/integrations/how-to/webhook/configure-operator-panel-webhook.md)

---

### Deeplink

**Що це:** Прямі посилання для запуску сценаріїв ботів з параметрами. Deeplink дозволяє створити унікальне посилання для кожного користувача або сценарію.

**Коли використовувати:**
- Потрібно запустити сценарій з рекламної кампанії з унікальними параметрами
- Потрібно передати ID клієнта або замовлення через посилання
- Потрібно створити персоналізовані посилання для різних груп користувачів
- Потрібно відстежувати джерело трафіку (UTM-мітки)

**Як працює:**
- Ви створюєте посилання з параметрами (наприклад, `https://t.me/mybot?start=customer_12345`)
- Користувач переходить за посиланням
- Параметр передається в сценарій через `{{messenger_input_param}}`
- Сценарій обробляє параметр та виконує відповідні дії

**Підтримувані месенджери:**
- Telegram
- Viber
- Facebook Messenger

**Детальніше:** → [Запуск сценарію через deeplink](/uk/integrations/explanation/deeplink-launch.md)

---

### send_request (обмін даними)

**Що це:** Action для відправки HTTP запитів з ConnectiveOne на зовнішні сервіси та отримання відповідей. Дозволяє обмінюватися даними між ConnectiveOne та зовнішніми системами безпосередньо в сценаріях.

**Коли використовувати:**
- Потрібно отримати дані з зовнішнього API (курс валют, погода, інформація про замовлення)
- Потрібно відправити дані на зовнішній сервіс (webhook, CRM, маркетингові платформи)
- Потрібно синхронізувати дані між ConnectiveOne та вашою системою
- Потрібно інтегрувати сценарії з третіми сторонами

**Як працює:**
- Ви налаштовуєте action `send_request` в сценарії з URL, методом, даними та заголовками
- ConnectiveOne відправляє HTTP запит на вказаний URL
- Відповідь обробляється через `response_mapping` або зберігається в state
- Дані стають доступними в сценарії через плейсхолдери

**Відмінності від send_me:**
- `send_request` не додає автоматично `chat_id` та `channel`
- `send_me` автоматично додає `chat_id` та `channel` (ідеально для webhook інтеграцій)

**Детальніше:**
- → [Отримання даних через send_request](/uk/integrations/how-to/data-transfer/get-data-via-send-request.md)
- → [Передача даних через send_request](/uk/integrations/how-to/data-transfer/send-data-via-send-request.md)

---

### Обмін даними з виджетом

**Що це:** Механізм передачі параметрів з сайту до сценарію та керування віджетом через JavaScript API. Дозволяє інтегрувати ConnectiveOne віджет з вашим сайтом для передачі контексту та керування поведінкою.

**Коли використовувати:**
- Потрібно передати параметри з сайту до сценарію (UTM-мітки, ID користувача, дані про товар)
- Потрібно керувати віджетом програмно (відкрити/закрити чат, змінити заголовок)
- Потрібно передати події з сайту до сценарію (клік по кнопці, перехід на сторінку)
- Потрібно інтегрувати віджет з SPA додатками

**Як працює:**
- Ви передаєте параметри через `params_from_site` при ініціалізації віджету
- Параметри автоматично додаються до кожного повідомлення та стають доступними в сценарії через `{{param_name}}`
- Ви використовуєте JavaScript API (`kw_event`) для керування віджетом з сайту
- Події з сайту можуть передаватися до сценарію через `emitevent`

**Основні можливості:**
- Передача параметрів через `params_from_site`
- Керування віджетом через `kw_event('openchat')`, `kw_event('command')`, `kw_event('emitevent')`
- Переініціалізація для SPA через `kw_event('kwreinitwidget')`
- Зміна параметрів під час роботи через `kw_event('kwsetparamsfromsite')`

**Детальніше:**
- → [Що таке widget](/uk/channels/explanation/what-is-widget.md)
- → [JavaScript API для widget](/uk/channels/explanation/widget-javascript-api.md)
- → [Передача параметрів з сайту](/uk/channels/how-to/pass-parameters-from-widget.md)
- → [Керування віджетом з сайту](/uk/channels/how-to/manage-widget-from-site.md)

---

## Як обрати тип інтеграції?

### Потрібно підключити зовнішню систему для обміну повідомленнями?
→ **Custom Channel**

### Потрібно отримати або змінити дані з ConnectiveOne?
→ **API (Enterprise API, Public API)**

### Потрібно запустити сценарій бота з вашої системи?
→ **call_node**

### Потрібно отримувати події з операторської панелі?
→ **Webhooks операторської панелі**

### Потрібно створити посилання для запуску сценарію з параметрами?
→ **Deeplink**

### Потрібно обмінюватися даними між ConnectiveOne та зовнішніми системами в сценаріях?
→ **send_request**

### Потрібно передати параметри з сайту до сценарію або керувати віджетом?
→ **Обмін даними з виджетом**

---

## Комбінування типів інтеграцій

Ви можете комбінувати різні типи інтеграцій для складних сценаріїв:

**Приклад:** Інтеграція з CRM
1. Використовуйте **API** для отримання даних про діалоги
2. Використовуйте **call_node** для відправки повідомлень клієнтам про статус замовлення
3. Використовуйте **Webhooks** для синхронізації статусів діалогів
4. Використовуйте **Deeplink** для створення персоналізованих посилань з реклами
5. Використовуйте **send_request** для отримання даних про замовлення з CRM в сценарії
6. Використовуйте **Обмін даними з виджетом** для передачі контексту з сайту до сценарію

---

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

### How-to інструкції
- [Використання API](/uk/integrations/how-to/use-api.md)
- [Інтеграція через Custom Channel](/uk/integrations/how-to/custom-channel/integrate-via-custom-channel.md)
- [Налаштування webhook панелі оператора](/uk/integrations/how-to/webhook/configure-operator-panel-webhook.md)
- [Запуск сценарію через API call_node](/uk/integrations/how-to/launch-scenario-via-call-node.md)
- [Отримання даних через send_request](/uk/integrations/how-to/data-transfer/get-data-via-send-request.md)
- [Передача даних через send_request](/uk/integrations/how-to/data-transfer/send-data-via-send-request.md)
- [Передача параметрів з сайту до сценарію](/uk/channels/how-to/pass-parameters-from-widget.md)
- [Керування віджетом з сайту](/uk/channels/how-to/manage-widget-from-site.md)

### Explanation статті
- [Запуск сценарію через deeplink](/uk/integrations/explanation/deeplink-launch.md)
- [Передача UTM-міток](/uk/integrations/explanation/utm-tags-transfer.md)

### Довідники
- [API довідник](/uk/integrations/reference/api-reference.md)