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:

  1. Відкрийте меню допомоги (іконка допомоги в правому верхньому куті інтерфейсу)
  2. Оберіть "API Documentation" або перейдіть за посиланням /api-docs
  3. 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 дозволяє:

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

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

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

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

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

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

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

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

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

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