# Про інтеграцію ConnectiveOne з Corezoid через операторську панель

Інтеграція ConnectiveOne з Corezoid дозволяє користувачам, які пишуть у Corezoid-бота, підключатися до живого оператора через ConnectiveOne, а всі повідомлення від оператора повертати назад у Corezoid. Це створює гібридне рішення, де Corezoid обробляє автоматизацію, а ConnectiveOne надає операторську підтримку.

## Контекст і проблема

У багатьох випадках потрібно поєднати автоматизацію Corezoid з живим оператором:
- Corezoid обробляє початкові запити та автоматизацію
- При потребі оператора запит передається в ConnectiveOne
- Оператор відповідає через ConnectiveOne, а повідомлення повертаються в Corezoid

Ця інтеграція вирішує задачу поєднання автоматизації та живих операторів у єдиному workflow.

## Основні концепції

### Архітектура взаємодії

Інтеграція працює через два сценарії ConnectiveOne:

**Сценарій #1 (на custom_channel):**
- Приймає вхідний запит від Corezoid
- Відкриває чат в операторській панелі ConnectiveOne
- Налаштовує `event_webhook_url` для пересилання подій

**Сценарій #2 (для подій з операторки):**
- Отримує події з операторської панелі через webhook
- Обробляє події через Action Jail
- Надсилає дані назад у Corezoid через Corezoid API

### Параметр event_webhook_url

Параметр `event_webhook_url` в action `operator_panel__connect_to_operator_with_msg` дозволяє вказати URL іншого бота, куди будуть надсилатися всі події з операторської панелі (повідомлення від оператора, клієнта, системні події).

## Варіанти підходів

### Пряма інтеграція vs через webhook

**Пряма інтеграція:**
- ✅ Плюси: Простіша реалізація
- ❌ Мінуси: Менша гнучкість, складніше масштабування

**Через webhook (рекомендовано):**
- ✅ Плюси: Гнучкість, виділення логіки, легко переробити без зміни інтеграцій
- ❌ Мінуси: Складніша початкова налаштування

**Чому використовуємо webhook:**
Це дозволяє виділити логіку обробки подій в окремий сценарій та легко адаптувати під різні зовнішні системи без зміни основного сценарію.

## Прийняті рішення

### Використання Action Jail для обробки подій

Action Jail дозволяє обробляти різні типи подій:
- `message_from_operator` — повідомлення від оператора
- `message_from_client` — повідомлення від клієнта
- `message_system` — системні події

### Збереження original_call_node_body

Для callback в Corezoid зберігається `original_call_node_body`, який використовується для повернення контролю в Corezoid після обробки події.

## Наслідки для користувачів і імплементації

### Для інтеграторів

При налаштуванні інтеграції важливо:

1. **Налаштувати два сценарії** — один для прийому запитів, інший для обробки подій
2. **Створити Action Jail** — для обробки різних типів подій та відправки в Corezoid
3. **Налаштувати event_webhook_url** — вказати URL другого бота для пересилання подій
4. **Обробити помилки** — додати retry логіку та fallback механізми

### Типові помилки

**Помилка:** Події не надходять у другий бот  
**Проблема:** Неправильно налаштований `event_webhook_url`  
**Рішення:** Перевірити URL та доступність другого бота

**Помилка:** Дані не повертаються в Corezoid  
**Проблема:** Не налаштований Action Jail або неправильний URL Corezoid API  
**Рішення:** Перевірити Action Jail та URL Corezoid API

**Помилка:** Втрачається контекст діалогу  
**Проблема:** Не зберігається `original_call_node_body`  
**Рішення:** Додати збереження та використання `original_call_node_body` для callback

### Переваги такого підходу

- **Гнучкість:** можна підключити будь-яку зовнішню систему, не лише Corezoid
- **Виділення логіки:** операторські події не перевантажують основний сценарій
- **Відокремленість:** легко переробити лише обробку jail'а без зміни в інтеграціях

## Пов'язані документи

- **Explanation:** [Підключення чату з оператором](/uk/operatorline/explanation/connect-chat-to-operator.md) — налаштування webhook через параметр `event_webhook_url`
- **How-to:** [Створити action в Action Jail](/uk/actionjail/how-to/admin-manage-actions.md) — як створити власні action