Як використовувати API ConnectiveOne

ConnectiveOne надає REST API для отримання та зміни даних, запуску сценаріїв та інтеграції з зовнішніми системами. Ця стаття пояснює основи роботи з API. Для повного списку endpoints та деталей дивіться API довідник.

Що можна робити через API?

Отримувати дані про діалоги, операторів, користувачів, тікети
Змінювати параметри діалогів (статус, тему, коментар)
Запускати сценарії ботів
Керувати даними через Custom Data API
Отримувати статистику та аналітику

Доступ до API документації

Для перегляду всіх доступних endpoints:

Відкрийте меню допомоги (іконка "?" у верхньому правому куті)
Оберіть "API документація"

Відкриється Swagger UI з повною документацією та можливістю тестування endpoints.

💡 Порада: Swagger UI дозволяє не тільки переглядати документацію, але й тестувати API endpoints безпосередньо в інтерфейсі.

Авторизація

Для виконання запитів до API необхідна авторизація. ConnectiveOne підтримує два типи авторизації:

API Key (спрощена авторизація)

Використовується для простих запитів. Ключ API можна отримати в Налаштування → Список ботів → Налаштування бота.

Формат заголовка:

Authorization: API-Key YOUR_API_KEY

Приклад curl:

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/general/KwBots/get \
  -H "Authorization: API-Key YOUR_API_KEY"

JWT Token (повноцінна авторизація)

Для корпоративних клієнтів доступна авторизація через JWT токен, яка включає функції оновлення токена, встановлення терміну дії та обмежень на швидкість запитів.

Формат заголовка:

Authorization: Bearer YOUR_JWT_TOKEN

Отримання JWT токена: Використовуйте endpoint /api/v1/auth/login для отримання JWT токена.

Основні типи запитів

GET (отримання даних)

Використовується для отримання даних з ConnectiveOne.

Формат:

GET https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/get

Приклад:

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/get \
  -H "Authorization: API-Key YOUR_API_KEY"

POST (створення/оновлення)

Використовується для створення або оновлення даних.

Формат:

POST https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/set

Приклад:

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/set \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "chatroom_id": 123
  }'

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

Успішна відповідь:

{
  "status": "success",
  "data": [...]
}

Помилка:

{
  "status": "error",
  "message": "Error description"
}

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

Приклад 1: Отримання списку діалогів

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/v1/OpChatRooms/list \
  -H "Authorization: API-Key YOUR_API_KEY"

Приклад 2: Зміна статусу діалогу

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Приклад 3: Зміна теми та статусу діалогу

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": 5,
    "status": "processed",
    "kw_chat_title": "New Title",
    "comment": "Updated via API"
  }'

Доступні модулі

Модуль Загальний

Список ботів
Зареєстровані клієнти

Модуль Панель оператора

Діалоги через панелі оператора
Оператори
Теми (тематики) в панелях операторів
Швидкі відповіді
Групи навичок

Модуль Custom Data

Всі дані з користувальницьких модулів

API для запуску сценаріїв

call_node - запуск сценарію через API
Entry Point URLs - прямі посилання для запуску

Безпека та обмеження

Безпека

Використовуйте HTTPS для всіх запитів
Зберігайте API ключі та токени в безпечному місці
Не передавайте ключі в публічних місцях або логах
Можна налаштувати список IP-адрес для обмеження доступу
Дані зберігаються відповідно до стандарту ISO 27001

Обмеження

Модуль API доступний для корпоративних користувачів
Необхідна авторизація для всіх запитів
Rate limiting може застосовуватися залежно від тарифного плану
Максимальний розмір даних обмежений налаштуваннями системи

Де знайти повну документацію?

Swagger UI в системі — меню допомоги → API документація (/api-docs)
API довідник — повний список endpoints

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

API довідник — повний список endpoints та параметрів
Запуск сценарію через API call_node
Що таке інтеграції — огляд типів інтеграцій