# Як інтегрувати зовнішню систему через Custom Channel

Custom Channel дозволяє інтегрувати ConnectiveOne з будь-якою зовнішньою системою, яка може відправляти та приймати HTTP запити. Це корисно для підключення існуючих ботів, CRM систем, або нових каналів комунікації.


## Коли використовувати Custom Channel?

Custom Channel підходить для таких кейсів:

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

## Передумови

Перед початком інтеграції переконайтеся, що:

- [ ] У вас є команда розробників на стороні зовнішньої системи, які мають досвід з REST API та JSON
- [ ] Ви можете керувати форматами запитів, які надсилає та отримує ваша система
- [ ] Ви спробували інтеграцію через Postman або інший HTTP клієнт
- [ ] Ви звернулися до підтримки ConnectiveOne у разі необхідності уточнень форматів запитів чи подій

## Як працює Custom Channel?

Custom Channel працює через послідовність HTTPS POST запитів:

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

**Вихідний потік (від ConnectiveOne до зовнішньої системи):**
- ConnectiveOne відправляє повідомлення та події на ваш `custom_channel_url`
- Ваша система обробляє вхідні повідомлення та події

## Налаштування

### Крок 1: Налаштування в ConnectiveOne

1. Перейдіть в **Налаштування ботів** → оберіть потрібного бота
2. Пролистайте до розділу **Custom Channel**
3. Налаштуйте наступні параметри:

- **`custom_channel_url`** — адреса вашого сервера, куди ConnectiveOne буде відправляти повідомлення
  - Для тестування можна використовувати сервіси типу [https://requestcatcher.com/](https://requestcatcher.com/)
- **`custom_channel x-access-token`** — токен, який ConnectiveOne буде передавати в хедері `x-access-token` кожного повідомлення
  - Якщо ваш сервіс не підтримує це, залиште пустим
- **`input_url`** — автогенероване поле, адреса на яку потрібно відправляти повідомлення
  - Це поле генерується автоматично після налаштування
- **`custom_channel kwizbot token`** — токен для підпису повідомлень, які надсилаються в ConnectiveOne
  - Вказується в хедері запиту як `x-auth-token`
  - Якщо залишити пустим, ConnectiveOne буде приймати повідомлення без токена

## Відправка повідомлень до ConnectiveOne

### Формат URL

```
POST https://{{engine_url}}/messengers_host/{{bot_id}}/custom_channel/hooks
```

Де:
- `engine_url` — `engine.ім'я_інстансу.connectiveone.io` або `engine-ім'я_інстансу.connectiveone.io`
- `bot_id` — ID бота зі сторінки налаштувань

### Приклад запиту

```json
{
  "update_id": 498995546,
  "message": {
    "from": {
      "id": "wregw3ergwergwergw==",
      "first_name": "",
      "last_name": "",
      "username": "Наталія",
      "language_code": "uk",
      "is_bot": false,
      "phone": "888888888888",
      "channel": "viber",
      "dialog_name": "Наталія"
    },
    "chat": {
      "id": "wregw3ergwergwergw==_viber"
    },
    "date": 1696408917974,
    "text": "Київ",
    "type": "text"
  }
}
```

> 🧑‍💻 **Примітка:** Для старту бота необхідно першим повідомленням відправляти `/start`.

### Параметри запиту

| Параметр | Тип | Опис |
|----------|-----|------|
| `update_id` | int | Унікальне значення |
| `message.from.id` | string | ID користувача |
| `message.from.first_name` | string | Ім'я користувача в операторській панелі |
| `message.from.last_name` | string | Прізвище користувача |
| `message.from.username` | string | Нік користувача |
| `message.from.language_code` | string | Код мови (uk, ru, en) |
| `message.chat.id` | string | Код чату користувача |
| `message.text` | string | Текст повідомлення (для старту: `/start`) |
| `message.type` | string | Тип повідомлення (text) |
| `message.from.dialog_name` | string | Ім'я чату для відображення в операторській панелі |

## Отримання повідомлень від ConnectiveOne

Ваш сервіс отримає POST запит на `custom_channel_url` з такими заголовками:

```http
POST /your_url HTTP/1.1
Host: your-service.com
Content-Type: application/json;charset=utf-8
User-Agent: ConnectiveOne
x-access-token: YOUR_TOKEN
```

**Приклад body запиту:**

```json
{
  "reply_markup": {
    "remove_keyboard": false
  },
  "chat_id": "398866",
  "text": "Notifications bot\nMy chat id: 398866,  channel custom_channel",
  "id": "71577138-fe1e-4ce7-b53e-0cec45ee3534",
  "from": "bot",
  "bot_id": 71,
  "type": "text"
}
```

## Типи повідомлень

### Вхідні повідомлення (які приймає ConnectiveOne)

- `text` — текст
- `image` — зображення
- `text_image` — текст з зображенням в одному повідомленні
- `video` — відео
- `audio` — аудіо-повідомлення
- `file` — файл

### Вихідні повідомлення (які відправляє ConnectiveOne)

- Текстові повідомлення
- Повідомлення з клавіатурою
- Слайдери
- Файли та зображення (у вигляді посилань)

## Типи подій (events)

ConnectiveOne відправляє наступні типи подій:

- `chat_created` — чат створено
- `auto_connected` — авто-під'єднання оператора
- `operator_connected` — оператор під'єднався
- `operator_disconnected` — оператор від'єднався
- `chat_closed_by_operator` — чат закрито оператором
- `chat_closed` — чат закрито
- `chat_closed_by_timeout` — чат закрито за таймаутом
- `connection_timeout` — таймаут з'єднання

### Приклад події `chat_created`

```json
{
  "reply_markup": {
    "remove_keyboard": false
  },
  "chat_id": "34122",
  "text": "Chat created",
  "event_name": "chat_created",
  "client": {
    "id": 572338,
    "first_name": "Test",
    "last_name": "Surname",
    "username": "testuername",
    "language_code": "uk",
    "phone": "+380505776464",
    "channel": "telegram"
  },
  "id": "83317aa1-8ea4-4c05-afed-d7437ff88fbf",
  "from": "bot",
  "bot_id": 4,
  "type": "text"
}
```

> 📖 **Документація:** Якщо вам потрібні тільки події з операторської панелі, розгляньте альтернативу через [Webhook панелі оператора](/uk/integrations/how-to/webhook/configure-operator-panel-webhook.md).

## Налаштування сценарію бота

### Крок 1: Відмітка каналу в блоках

В сценарії бота, після елементу **"Початок секції"**, необхідно в розширених налаштуваннях відмітити **custom_channel** для всіх блоків, які будуть взаємодіяти з Custom Channel.

### Крок 2: Налаштування виходу зі сценарію

Для закінчення сценарію:

1. Створіть блок **"Повідомлення користувачу"** з умовним словом для виходу (наприклад, `/exit`)
2. В константах вкажіть `close_chat_command` зі значенням `/exit`
3. В розширених налаштуваннях блока:
   - Зніміть відмітки на всіх месенджерах
   - Залиште відмітку **custom_channel**

## Отримання доступних операторів

### Endpoint

```
POST https://engine-projectname.connectiveone.io/kw/custom_channel/operators_available
```

### Приклад використання

```bash
curl --location --request POST 'https://engine-projectname.connectiveone.io/kw/custom_channel/operators_available' \
--data ''
```

### Формат відповіді

```json
{
  "status": "success",
  "data": [
    {
      "id": 56,
      "max_dialogs": 30,
      "rooms_count": 0,
      "max_dialog_id": 498
    }
  ]
}
```

## Обмеження

- Custom Channel працює тільки через HTTPS
- Необхідна налаштування webhook endpoint на стороні зовнішньої системи
- Timeout запитів залежить від налаштувань системи
- Рекомендується використовувати retry логіку для надійності

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

- [Налаштування webhook панелі оператора](/uk/integrations/how-to/webhook/configure-operator-panel-webhook.md)
- [Що таке інтеграції](/uk/integrations/explanation/what-are-integrations.md)