Автентифікація
API підключення використовує автентифікацію за допомогою токенів-носіїв. Усі запити повинні містити дійсний токен доступу JWT у заголовку авторизації.
Отримати токен
Надішліть свої облікові дані до кінцевої точки автентифікації. Ви отримаєте короткочасний access_token та довговічний refresh_token.
Використайте токен
Включайте токен у кожен запит:
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"access_token": "eyJhbG...",
"refresh_token": "dGhpcw...",
"expires_in": 3600,
"token_type": "Bearer"
}Базова URL-адреса та керування версіями
Усі кінцеві точки API мають версії /api/v1/. Базова URL-адреса залежить від вашого розгортання.
Для розгортань, розміщених у хмарі, використовуйте регіональну кінцеву точку, призначену вашій організації. Для локальних розгортань сервера використовуйте ім'я хоста вашого сервера.
| Навколишнє середовище | Базова URL-адреса |
|---|---|
| Хмара (США) | https://beta.connection.app/api/v1 |
| Локальна версія | https://<your-server>/api/v1 |
Усі тіла запитів та відповідей використовують application/json. Включайте Content-Type: application/json до запитів з тілом.
Помилки та коди стану
API використовує стандартні коди стану HTTP. Відповіді на помилки включають машиночитаний код та повідомлення, що читається людиною.
| Статус | Значення |
|---|---|
| 200 | Успіх |
| 201 | Створено |
| 400 | Неправильний запит — недійсні параметри |
| 401 | Неавторизовано — відсутній або закінчений токен |
| 403 | Заборонено — недостатньо дозволів |
| 404 | Не знайдено |
| 500 | Внутрішня помилка сервера |
{
"error": {
"code": "device_not_found",
"message": "No device with that UUID exists in your organization",
"status": 404
}
}Огляд REST API
REST API сервера підключень забезпечує повний програмний доступ до вашого парку пристроїв, комунікаційної інфраструктури та аналітики. Він дотримується RESTful-конвенцій з тілами запитів/відповідей JSON.
Автентифікація
Аутентифікація на основі токенів. Вхід повертає токен, який має бути надісланий як Авторизація: Токен<token> на всі наступні запити.
Користувачі
Створення та керування обліковими записами користувачів. Кінцева точка GET /users/user повертає поточного автентифікованого користувача.
Пристрої
Перераховувати та перевіряти пристрої, керувати зв'язками між користувачами та пристроями, читати та записувати налаштування та стан кожного пристрою, керувати образами прошивки та сховища, а також отримувати журнали та звіти про збої.
Проксі-сервер CBBP
Надішліть будь-яку команду CBBP на пристрій через сервер. Сервер передає команду через Wi-Fi-з’єднання пристрою та повертає відповідь пристрою. Відповідь outgoing-make також містить повідомлення CBBMPessage, яке пристрій виконує негайно.
Тіло запиту – це конверт команди CBBP. Збережений об'єкт CBBPCommand відстежує статус доставки: UNSET → SENT → RECEIVED або TIMED_OUT.
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}Канали
Канали – це основні комунікаційні примітиви. До типів належать ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService та ChannelRecorder.
Зв'язок
Ініціювати та керувати активними сеансами зв'язку — вихідними викликами, VCP, записом та потоковою передачею контенту. Відповідь на вихідний виклик містить повідомлення CBBPMessage, на яке пристрій реагує негайно.
Аудіоміст
Отримайте доступ до записаних розмов у містку, включаючи повні стенограми, списки учасників та зведені за допомогою штучного інтелекту підсумки. Підтримує кілька шаблонів підсумків (нотатки до зустрічей, нотатки до занять, охорона здоров'я тощо) та генерацію аудіо TTS для підсумків.
Розмови
Сеанси розмов на базі штучного інтелекту з використанням ChatGPT, Gemini або вбудованого движка. Підтримка кількох персонажів (лікар, репетитор, механік тощо) та розбиття історії повідомлень на сторінки.
Зміст
Переглядайте та відтворюйте потоковий аудіоконтент на пристроях. Контент організовано в дерево категорій; популярний контент можна фільтрувати за містом, регіоном або країною.
Місця розташування
Перетворити географічні координати на структурований об'єкт міста, регіону та країни. Використовується пристроями під час отримання контексту.
Push-сповіщення
Зареєструйте мобільний додаток, щоб отримувати push-сповіщення FCM. Підтримує iOS, Android та веб-сайти.
Зберігання
Завантажити файли, що зберігаються на об'єктах моделі, та виконати видалення фону зображення (повертає результат у кодуванні base64).
Масові операції
Виконайте кілька операцій API в одному HTTP-запиті. Передайте single_transaction=true, щоб об’єднати всі операції в одну атомарну транзакцію — збій будь-якого елемента скасовує весь пакет.
Дата та час
Повертає поточну дату та час сервера у форматі GMT+0. Не потребує автентифікації. Використовується пристроями для синхронізації їхнього внутрішнього годинника.
Базовий протокол Com Badge
CBBP — це легкий протокол команд JSON для прямої взаємодії з значками підключення. Він надає вам повний контроль над усіма апаратними та програмними функціями пристрою.
Формат повідомлення
Кожна взаємодія CBBP складається з командного повідомлення, що надсилається на пристрій, та повідомлення з результатом, що повертається пристроєм.
Поле об'єкта як у запиті, так і у відповіді містить дані, що стосуються команди, і може бути пропущено, якщо воно не потрібне.
{
"command": "command_name",
"object": {
// optional command parameters
}
}{
"result": 0, // 0 = success, -1 = error
"detail": "ok", // human-readable status
"object": { // optional response data
// command-specific fields
}
}Транспорт
Повідомлення CBBP можуть бути доставлені на бейдж трьома різними способами транспортування залежно від вашої архітектури інтеграції.
Bluetooth (додаток)
Надсилайте команди CBBP безпосередньо з мобільного додатку через BLE. Потрібно, щоб пристрій був сполучений та знаходився в зоні дії.
Мобільний SDKWi-Fi або Bluetooth через сервер
Проксі-сервер CBBP через REST API — POST /devices//cbbp. Сервер автоматично перенаправляє пристрій через WiFi або Bluetooth залежно від того, як підключено бейдж. Найпоширеніше для бекенд-інтеграцій.
REST APIВнутрішня диспетчеризація
Диспетчеризація CBBP на пристрої або між процесами. Використовується прошивкою бейджа для маршрутизації команд між внутрішніми підсистемами.
Тільки прошивкаКоманди живлення
Контроль стану живлення пристрою — сплячий режим, пробудження, перезавантаження та скидання до заводських налаштувань.
Команди Wi-Fi
Налаштуйте бездротові мережі, шукайте точки доступу, перевіряйте стан підключення та керуйте збереженими обліковими даними.
Команди Bluetooth
Керуйте рекламою BLE, сполученням та зв'язком між значками.
Команди налаштувань
Читання та запис конфігурації пристрою — відображуване ім’я, часовий пояс, мова та прапорці функцій.
Команди прошивки
Запускати оновлення прошивки через Інтернет, перевіряти стан оновлень та запитувати поточну версію прошивки на пристрої.
Команди пристрою
Життєвий цикл пристрою, автентифікація, конфігурація, ведення журналу, стан та керування обладнанням.
Команди зв'язку
Здійснюйте дзвінки, надсилайте повідомлення, керуйте активними сеансами зв'язку та контролюйте запис.
Аудіокоманди
Керуйте гучністю динаміка, підсиленням мікрофона, аудіопрофілями та відтворенням тексту в мовлення.
Команди світлодіодів
Встановіть колір, яскравість та анімаційні шаблони світлодіода для індикатора значка.
Внутрішні команди
Внутрішні команди відправлення, що використовуються для доставки контексту, історії каналу, вокалізації та декодування аудіо.
Мобільні команди
Команди для координації значка з підключеним мобільним додатком — push-сповіщення, синхронізація стану додатка та глибоке посилання.