Як інтегрувати зовнішню систему через 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

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

custom_channel_url — адреса вашого сервера, куди ConnectiveOne буде відправляти повідомлення
- Для тестування можна використовувати сервіси типу 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 бота зі сторінки налаштувань

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

{
  "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 з такими заголовками:

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 запиту:

{
  "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`

{
  "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 панелі оператора.

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

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

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

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

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

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

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

Endpoint

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

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

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

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

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

Обмеження

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