API Reference — Довідник по API ConnectiveOne

API Reference містить загальну інформацію про ConnectiveOne API, навігацію до Swagger документації та приклади основних сценаріїв використання. Для детальної інформації про всі endpoints використовуйте Swagger UI в системі.

Що таке ConnectiveOne API?

ConnectiveOne API — це REST API для інтеграції з платформою ConnectiveOne. API дозволяє:

Отримувати дані про чати, тікети, користувачів
Надсилати повідомлення клієнтам через сценарії ботів
Керувати даними через Custom Data API
Отримувати статистику та аналітику
Інтегруватися з іншими системами

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

Swagger документація доступна безпосередньо в інтерфейсі ConnectiveOne:

Відкрийте меню допомоги (іконка допомоги в правому верхньому куті інтерфейсу)
Оберіть "API Documentation" або перейдіть за посиланням /api-docs
Swagger UI відкриється з повною документацією по всіх API endpoints

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

Автентифікація

ConnectiveOne API підтримує два типи автентифікації:

JWT Bearer Token

Використовується для автентифікації через JWT токен:

Authorization: Bearer YOUR_JWT_TOKEN

x-auth-token

Використовується для автентифікації через зовнішній токен:

x-auth-token: YOUR_TOKEN

📖 Детальніше: Повну інформацію про автентифікацію та отримання токенів дивіться в Swagger UI в розділі "Authentication" або в технічній документації.

Основні групи API

ConnectiveOne API організований за модулями та функціональністю. Нижче наведено перелік основних груп endpoints:

Authentication

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

Основні endpoints:

Логін користувача
Оновлення токену
Вихід з системи

📖 Детальніше: Дивіться в Swagger UI в розділі "Authentication".

Users

Endpoints для управління користувачами системи.

Основні endpoints:

Отримання списку користувачів
Отримання користувача за ID
Створення та оновлення користувачів

📖 Детальніше: Дивіться в Swagger UI в розділі "Users".

Chats

Endpoints для роботи з чатами та діалогами.

Основні endpoints:

Отримання списку чатів (/kw/api/v1/OpChatRooms/list)
Отримання чату за ID
Фільтрація, сортування та пагінація

Функціонал:

Фільтрація за датою створення, статусом, оператором
Сортування за різними полями
Пагінація результатів
Включення пов'язаних даних (include)

📖 Детальніше: Дивіться в Swagger UI в розділі "Chats".

Tickets

Endpoints для роботи з тікетами.

Основні endpoints:

Отримання списку тікетів (/kw/api/v1/Ticket/list)
Отримання тікету за ID
Створення та оновлення тікетів

Функціонал:

Фільтрація за датою створення, статусом, пріоритетом
Сортування за різними полями
Пагінація результатів
Включення пов'язаних даних (include)

📖 Детальніше: Дивіться в Swagger UI в розділі "Tickets".

Broadcast

Endpoints для роботи з масовими розсилками.

Основні endpoints:

Створення розсилок
Управління шаблонами розсилок
Перегляд результатів розсилок

📖 Детальніше: Дивіться в Swagger UI в розділі "Broadcast".

Custom Data

Endpoints для роботи з кастомними даними та моделями.

Основні endpoints:

Отримання даних з кастомних моделей
Створення та оновлення записів
Пошук та фільтрація даних

📖 Детальніше: Дивіться в Swagger UI в розділі "Custom Data".

Call Node

Endpoints для виклику сценаріїв ботів та надсилання повідомлень.

Основні endpoints:

Виклик сценарію через call_node (/kw/api/call_node/)
Надсилання повідомлень клієнтам

📖 Детальніше: Дивіться в Swagger UI в розділі "Call Node".

Statistics

Endpoints для отримання статистики та аналітики.

Основні endpoints:

Отримання статистики операторів
Отримання статистики діалогів
Отримання метрик SLA

📖 Детальніше: Дивіться в Swagger UI в розділі "Statistics".

Quality Assurance

Endpoints для роботи з системою контролю якості.

Основні endpoints:

Отримання оцінок якості
Управління критеріями оцінки

📖 Детальніше: Дивіться в Swagger UI в розділі "Quality Assurance".

Приклади основних сценаріїв

Надсилання повідомлення через call_node

Надсилання повідомлення клієнту через виклик сценарію бота:

Endpoint:

POST /kw/api/call_node/{bot_id}/{node_id}/{channel}/{chat_id}

Або через JSON body:

POST /kw/api/call_node/

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

{
  "bot_id": 1,
  "connector_alias": "entry_point_alias",
  "channel": "telegram",
  "chat_id": "567890",
  "data": {
    "message": "Ваше замовлення готове!"
  }
}

📖 Детальніше: Дивіться в Swagger UI в розділі "Call Node".

Отримання списку чатів

Отримання списку чатів з фільтрацією та пагінацією:

Endpoint:

GET /kw/api/v1/OpChatRooms/list

Приклад запиту з параметрами:

GET /kw/api/v1/OpChatRooms/list?filter[createdAt][gt]=2024-12-01T00:00:00.000Z&filter[createdAt][lt]=2024-12-29T00:00:00.000Z&limit=10&offset=0&order[createdAt]=desc

Параметри:

filter[createdAt][gt] — фільтр за датою створення ВІД
filter[createdAt][lt] — фільтр за датою створення ДО
limit — кількість записів (за замовчуванням 10)
offset — кількість записів для пропуску
order[createdAt] — сортування (desc або asc)

📖 Детальніше: Дивіться в Swagger UI в розділі "Chats".

Отримання списку тікетів

Отримання списку тікетів з фільтрацією та пагінацією:

Endpoint:

GET /kw/api/v1/Ticket/list

Приклад запиту з параметрами:

GET /kw/api/v1/Ticket/list?filter[createdAt][gt]=2024-12-01T00:00:00.000Z&filter[createdAt][lt]=2024-12-29T00:00:00.000Z&limit=10&offset=0&order[createdAt]=desc

Параметри:

filter[createdAt][gt] — фільтр за датою створення ВІД
filter[createdAt][lt] — фільтр за датою створення ДО
limit — кількість записів (за замовчуванням 10)
offset — кількість записів для пропуску
order[createdAt] — сортування (desc або asc)

📖 Детальніше: Дивіться в Swagger UI в розділі "Tickets".

Як використовувати Swagger UI

Swagger UI в ConnectiveOne дозволяє:

Переглядати документацію — детальний опис всіх endpoints, параметрів та відповідей
Тестувати API — виконувати запити безпосередньо в інтерфейсі
Переглядати схеми — структури даних для запитів та відповідей
Копіювати приклади — готові приклади запитів для використання в коді

Як відкрити Swagger UI

Відкрийте меню допомоги (іконка допомоги в правому верхньому куті)
Оберіть "API Documentation" або перейдіть за посиланням /api-docs
Swagger UI відкриється з повною документацією

Як тестувати API в Swagger UI

Знайдіть потрібний endpoint в Swagger UI
Натисніть "Try it out"
Заповніть параметри запиту
Натисніть "Execute"
Перегляньте відповідь та код запиту

💡 Порада: Swagger UI автоматично додає токен автентифікації з вашої сесії, тому вам не потрібно вручну додавати заголовки автентифікації.

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

Для детальної інформації про всі API endpoints:

Swagger UI в системі — меню допомоги → API Documentation (/api-docs)
Swagger JSON — https://engine-{instancename}.kwizbot.io/swagger.json

Пов'язані матеріали

Як використовувати API — інструкція з використання API