Як використовувати 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"
  }'