Платформа за разработчици

Надграждайте върху
Платформа за свързване

Два мощни API — RESTful сървърен API за управление на устройства и оркестрация на комуникацията и ниско ниво CBBP протокол за директен контрол на значки.

Справочник за REST APIПротокол CBBP
OpenAPI 3.0JSON / RESTBluetooth + WiFiПоддръжка на уебкукички
Connection Studio
Explorer
examples
send_command.http
response.json
list_devices.http
webhooks.http
src
docs
send_command.http
response.json
# Send a CBBP command via the server
POST /api/v1/devices/{uuid}/cbbp

{
  "command": "speak",
  "object": {
    "text": "Shift starts in 5 minutes",
    "volume": 85,
    "language": "en-US"
  }
}

# Response
{
  "result": 0,
  "detail": "ok"
}
main
HTTPUTF-8Ln 2, Col 1

REST API

Пълно управление на жизнения цикъл на устройството — осигуряване, конфигурация, фърмуер, комуникации и анализи — през стандартния HTTPS.

Разгледайте REST API →

Протокол CBBP

Com Badge Basic Protocol — JSON команден протокол за директен контрол на устройството през Bluetooth (приложение), WiFi (прокси сървър) или локално изпращане.

Разгледайте CBBP →

Уеб кукички

Абонирайте се за събития на устройството в реално време – комуникации, промени в състоянието, актуализации на местоположението – доставяни като HTTP POST полезни товари до вашата крайна точка.

Разгледайте уебкукичките →

Early Access: The Connection API is currently available by special request to select partners. Contact us to apply for access.

Pro or Plus plan required: Badges must be on the Pro or Plus plan to be controlled via the API.

Първи стъпки

Удостоверяване

API за връзка използва удостоверяване с Bearer token. Всички заявки трябва да включват валиден JWT access token в заглавката Authorization.

Вземете жетон

ИЗПРАТЕТЕ вашите идентификационни данни до крайната точка за удостоверяване. Ще получите краткотраен access_token и по-дълготраен refresh_token.

Използвайте токена

Включете токена във всяка заявка:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Заявка
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Отговор 200
{
  "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

REST API на Connection Server предоставя пълен програмен достъп до вашия парк от устройства, комуникационна инфраструктура и анализи. Той следва RESTful конвенции с JSON тела на заявка/отговор.

API удостоверяване
Потребители
Устройства
Канали
Комуникация
Аудио мост
Разговори
Съдържание
Местоположения
Push известия
Съхранение
Масови операции
Дата и час

Удостоверяване

Удостоверяване, базирано на токени. Влизането връща токен, който трябва да бъде изпратен като Авторизация: Токен<token> при всички последващи заявки.

POST/api/v1/loginУдостоверяване на потребител и получаване на токен за удостоверяване
POST/api/v1/login-deviceУдостоверяване на устройство чрез UUID и MAC адрес
POST/api/v1/logoutАнулиране на текущия токен на сесията

Потребители

Създаване и управление на потребителски акаунти. Крайната точка GET /users/user връща текущо удостоверения потребител.

GET/api/v1/users/userИзвличане на текущо влезлия потребителски профил
POST/api/v1/users/userСъздаване на нов потребителски акаунт
PATCH/api/v1/users/user/{uuid}Актуализиране на потребителския профил (напр. изображение на профила)

Устройства

Изброявайте и проверявайте устройства, управлявайте асоциациите потребител-устройство, четете и записвайте настройки и състояние за всяко устройство, обработвайте фърмуер и изображения на паметта и получавайте регистрационни файлове и отчети за сривове.

GET/api/v1/devices/deviceИзбройте всички устройства
GET/api/v1/devices/device/{uuid}Получете подробна информация за устройството, включително фърмуер и настройки
PUT/api/v1/devices/association/{uuid}Актуализиране на връзката между потребител и устройство
DELETE/api/v1/devices/association/{uuid}Премахване на връзката потребител-устройство и съхранените настройки
GET/api/v1/devices/device/{device_uuid}/settingsИзбройте настройките, съхранени за устройство
POST/api/v1/devices/device/{device_uuid}/settingsЗапазване на настройките, специфични за устройството
GET/api/v1/devices/device/{device_uuid}/statusПолучаване на състоянието на устройството (свързаност, батерия, сензори, състояние на звука)
POST/api/v1/devices/device/{device_uuid}/statusПубликуване на състоянието на устройството от устройството
GET/api/v1/devices/device/{device_uuid}/contextИзбройте контекстните стойности, съхранени за устройството
POST/api/v1/devices/device/{device_uuid}/ingest-contextПолучаване на GPS + WiFi контекст от устройството
GET/api/v1/devices/firmwareИзбройте версиите на фърмуера, съвместими с дадена версия на хардуера/софтуера
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchИзвличане на образ на фърмуера на парчета
GET/api/v1/devices/languageСписък на поддържаните езици и гласове на устройството
GET/api/v1/devices/storage_imageИзтегляне на персонализирано изображение за съхранение на устройство за дадена локализация
POST/api/v1/devices/logПолучаване на лог файл от устройство
POST/api/v1/devices/crashПолучаване на дъмп на ядрото от устройство
PATCH/api/v1/devices/crash/{uuid}Актуализиране на запис за срив

CBBP прокси

Изпратете всяка CBBP команда към устройство чрез сървъра. Сървърът препредава командата през WiFi връзката на устройството и връща отговора на устройството. Отговорът „outgoing-make“ също така вгражда CBBPSessage, който устройството изпълнява незабавно.

POST/api/v1/devices/device/{device_uuid}/cbbpИзпратете CBBP команда към устройство чрез сървъра
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Извличане на състоянието и отговора на предишно изпратена CBBP команда

Тялото на заявката е плик на CBBP команда. Съхраненият обект CBBPCommand проследява състоянието на доставка: UNSET → SENT → RECEIVED или TIMED_OUT.

Изпълнете заявка с GET /cbbp/, за да проверите дали устройството е получило и е отговорило на командата.
Заявка — outgoingMessage
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Отговор — Статус на CBBPCommand
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Канали

Каналите са основните комуникационни примитиви. Типовете включват ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService и ChannelRecorder.

GET/api/v1/channels/channelИзбройте каналите, по избор филтрирани по object_type
POST/api/v1/channels/channelСъздаване на канал (ChannelGroup, ChannelContact или ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Актуализиране на ChannelGroup или ChannelContact
DELETE/api/v1/channels/channel/{uuid}Изтриване на канал
DELETE/api/v1/channels/{uuid}Изтриване на група канали
DELETE/api/v1/channels/by-type/{channelType}Изтриване на всички канали от даден тип (в момента ChannelContact)
GET/api/v1/channels/associationИзбройте асоциациите на каналите за текущия потребител
POST/api/v1/channels/associationЗаявка за асоцииране с канал
PATCH/api/v1/channels/association/{uuid}Приемане, отхвърляне или актуализиране на настройките за свързване
DELETE/api/v1/channels/association/{uuid}Премахване на асоциация с канал
GET/api/v1/channels/historyПолучаване на история на достъп до страницирани канали за текущия потребител
POST/api/v1/channels/historyСъздаване на запис в историята на канала
GET/api/v1/channels/searchТърсене на канали по низ на заявка и опционален филтър по тип

Комуникация

Инициирайте и управлявайте активни комуникационни сесии — изходящи повиквания, VCP, запис и стрийминг на съдържание. Отговорът за изходящо създаване включва CBBPMessage, по който устройството реагира незабавно.

POST/api/v1/communicate/outgoing-makeИницииране на изходящ канал към ChannelPeople, ChannelGroup, ChannelContact или ChannelContactNumber
POST/api/v1/communicate/incoming-acceptanceПриемане или отхвърляне на входяща заявка за присъединяване към канал
POST/api/v1/communicate/closeЗатваряне на текущия активен комуникационен канал на устройство
POST/api/v1/communicate/vcp-activateИнициирайте протокола за гласова комуникация (VCP) на сървъра и устройството
POST/api/v1/communicate/vcp-deactivateДеактивиране на VCP, връщане към всеки предишен канал
POST/api/v1/communicate/recording-activateАктивирайте режим на запис на сървъра и устройството
POST/api/v1/communicate/content-startОтваряне на стрийминг канал за аудио съдържание
POST/api/v1/communicate/request-vocalizationГенериране на TTS аудио за дадения текст, като по избор се превежда

Аудио мост

Достъп до записани разговори в моста, включително пълни преписи, списъци с участници и генерирани от изкуствен интелект обобщения. Поддържа множество шаблони за обобщения (бележки от срещи, бележки от класове, здравеопазване и др.) и генериране на TTS аудио за обобщения.

GET/api/v1/bridge/conversationsИзбройте всички разговори в моста
GET/api/v1/bridge/conversations/{uuid}Получете подробен разговор, включително препис, участници и резюме
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryГенериране на обобщение с изкуствен интелект за разговор
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioГенериране на аудио за обобщение на разговора

Разговори

Разговорни сесии, задвижвани от изкуствен интелект, използващи ChatGPT, Gemini или вградения енджин. Поддържа множество персонажи (Лекар, Преподавател, Механик и др.) и история на съобщенията, разделена на страници.

GET/api/v1/conversations/conversationСписък на сесии за генериране на AI, филтрируеми по персона и инструмент
POST/api/v1/conversations/conversationСъздаване на нова сесия за разговор с изкуствен интелект
GET/api/v1/conversations/conversation/{uuid}Извличане на сесия на разговор с опционално обобщение/актуализация при отсъствие
DELETE/api/v1/conversations/conversation/{uuid}Изтриване на сесия на разговор
GET/api/v1/conversations/conversation/{uuid}/messagesИзброяване на съобщения в разговор
POST/api/v1/conversations/conversation/{uuid}/messagesДобавете потребителско съобщение и получете отговор от изкуствен интелект

Съдържание

Разглеждайте и възпроизвеждайте стрийминг аудио съдържание на устройства. Съдържанието е организирано в дърво на категории; популярното съдържание може да бъде филтрирано по град, регион или държава.

GET/api/v1/content/categoriesПолучете дърво от категории съдържание
GET/api/v1/content/contentИзбройте наличното съдържание в дадена категория
GET/api/v1/content/popularИзбройте популярно съдържание за даден град, регион или държава

Местоположения

Преобразува географските координати в структуриран обект град, регион и държава. Използва се от устройства при приемане на контекст.

POST/api/v1/location/determineРазграничаване на географска ширина/дължина до град, регион и държава

Push известия

Регистрирайте мобилно приложение, за да получавате FCM push известия. Поддържа iOS, Android и уеб приложения.

POST/api/v1/push-notifications/pushРегистрирайте мобилно приложение за FCM push известия (iOS, Android, уеб)

Съхранение

Изтеглете файлове, съхранени в обекти на модела, и изпълнете премахване на фона на изображението (връща резултат, кодиран в base64).

GET/api/v1/storage/retrieve/{path}Изтегляне на съхранен файл по път
POST/api/v1/storage/remove-backgroundПремахване на фона от изображение (връща base64)

Масови операции

Изпълнете множество API операции в една HTTP заявка. Предайте single_transaction=true, за да обгърнете всички операции в една атомарна транзакция — неуспех на който и да е елемент отменя целия пакет.

POST/api/v1/bulkИзпълнявайте множество API операции в една заявка, по избор като една атомна транзакция

Дата и час

Връща текущата дата и час на сървъра в GMT+0. Не изисква удостоверяване. Използва се от устройствата за синхронизиране на вътрешния им часовник.

GET/api/v1/current-datetimeВръща текущата дата и час в GMT+0
Протокол CBBP

Основен протокол за Com Badge

CBBP е лек JSON команден протокол за директно взаимодействие с Connection Badges. Той ви дава пълен контрол над всяка хардуерна и софтуерна функция на устройството.

Формат на съобщението

Всяко CBBP взаимодействие се състои от командно съобщение, изпратено до устройството, и резултатно съобщение, върнато от устройството.

Полето за обект както в заявката, така и в отговора съдържа специфични за командата данни и може да бъде пропуснато, когато не е необходимо.

Пълната документация на протокола е достъпна за регистрирани партньори. Свържете се с вашия бизнес представител на Connection или се свържете с developer@connectionbadge.com да поискате достъп до пълния справочник за командите на 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. Изисква устройството да е сдвоено и в обхват.

Мобилен SDK

WiFi или Bluetooth чрез сървър

Прокси CBBP чрез REST API — POST /devices//cbbp. Сървърът автоматично се насочва към устройството през WiFi или Bluetooth, в зависимост от това как е свързан значката. Най-често срещано за backend интеграции.

REST API

Вътрешна експедиция

Изпращане на CBBP на устройството или междупроцесно. Използва се от фърмуера на значката за маршрутизиране на команди между вътрешни подсистеми.

Само фърмуер

Команди за захранване

Контролирайте състоянието на захранването на устройството — заспиване, събуждане, рестартиране и възстановяване на фабричните настройки.

PowerRebootРестартирайте устройството незабавно.
PowerDeepsleepВлезте в режим на дълбок сън (ниска мощност).
FactoryResetИзтрийте всички конфигурации и върнете към фабричните настройки.

WiFi команди

Конфигурирайте безжични мрежи, сканирайте за точки за достъп, проверявайте състоянието на връзката и управлявайте запазените идентификационни данни.

WiFiScanСканирайте за налични точки за достъп до WiFi.
WiFiAPTestТествайте свързаността с конкретна WiFi точка за достъп.
WiFiAPJoinПрисъединете се към WiFi точка за достъп с предоставените идентификационни данни.

Bluetooth команди

Контролирайте BLE рекламирането, сдвояването и комуникацията между значки.

BTScanBTСканирайте за класически Bluetooth устройства.
BTScanBLEСканирайте за BLE устройства.
DeviceBLEServiceAvailableМаркирайте услугата BLE като налична.
DeviceBLEServiceUnavailableМаркирайте услугата BLE като недостъпна.
DeviceBLEActiveЗадайте BLE радиото в активно състояние.
DeviceBLEIdleЗадайте BLE радиото в състояние на готовност.
DeviceBLEAdvChannelAddДобавете канал към рекламния полезен товар на BLE.
DeviceBTScanСтартирайте сканиране на Bluetooth устройства.
DeviceBTA2DStartСтартирайте Bluetooth A2DP аудио стрийминг.
DeviceBTA2DEndКрай на Bluetooth A2DP аудио стрийминга.
DeviceBTNativeAssistStartСтартирайте вградения гласов асистент Bluetooth.
DeviceBTNativeAssistEndПрекратете вградения гласов асистент Bluetooth.

Команди за настройки

Четене и запис на конфигурацията на устройството — показвано име, часова зона, език и флагове на функциите.

SettingsListGetИзвличане на всички настройки като списък с ключ-стойност.
SettingsListSetЗапишете няколко стойности на настройките едновременно.
SettingsGetПолучете стойността на една настройка по ключ.
SettingsSetЗадайте стойността на една настройка.
SettingsSendИзпратете текущите настройки към сървъра.
SettingsClearИзчистване на специфични стойности на настройките.
SettingsEraseИзтрийте всички запазени настройки.

Команди на фърмуера

Задействайте OTA актуализации на фърмуера, проверете състоянието на актуализациите и заявете текущата версия на фърмуера на устройството.

FirmwareCheckПроверете дали е налична актуализация на фърмуера.
FirmwareUpdateЗапочнете OTA актуализация на фърмуера.
FirmwareValidateПроверете целостта на изтегления образ на фърмуера.

Команди на устройството

Жизнен цикъл на устройството, удостоверяване, конфигурация, регистриране, състояние и контрол на хардуера.

NoOpБез операция / поддържане на активност.
TestОсновен тест за свързаност.
DeviceDateTimeПолучаване или задаване на датата и часа на устройството.
DeviceAuthenticateУдостоверете устройството със сървъра.
DeviceConfigureПриложете полезен товар за конфигурация към устройството.
DevicePostConnectionTasksИзпълнете задачи за инициализация след свързване.
DeviceStorageLoadЗареждане на данни от хранилището на устройството.
DeviceLoadCustomAudioЗаредете персонализирани аудио файлове на устройството.
DeviceCoredumpSendКачете дъмп на ядрото на срив на сървъра.
DeviceAttachСвържете устройството към сървърна сесия.
DeviceDetachОткачете устройството от сървърна сесия.
DeviceLogSendКачете лог файловете на устройството на сървъра.
DeviceConnectionTestТествайте свързаността на сървъра.
DeviceStatusSendИзпращане на състоянието на устройството към сървъра.
DeviceStatusGetПолучете текущото състояние на устройството.
DeviceInteractionЗадействане на събитие за взаимодействие с устройство.
DeviceSetAPIHostЗадайте хоста на API сървъра.
DeviceTestMicsИзвършете самотест на микрофона.
HardwareI2CCommandИзпратете сурова I2C команда към хардуерна периферия.

Комуникационни команди

Инициирайте повиквания, изпращайте съобщения, управлявайте активни комуникационни сесии и контролирайте записа.

CommunicateChannelJoinПрисъединете се към комуникационен канал.
CommunicateChannelLeaveОставете комуникационен канал.
CommunicateChannelChangeПревключете на друг канал.
CommunicateChannelCloseЗатворете комуникационен канал.
CommunicateReceiveIncomingУведомете устройството за входяща комуникация.
CommunicateRequestOutgoingЗаявете изходяща комуникация.
CommunicateVCPActivateАктивирайте сесията на протокола за гласова комуникация.
CommunicateVCPDeactivateДеактивирайте VCP сесията.
CommunicateRecordingActivateЗапочнете запис на активната комуникация.
CommunicateIncomingAcceptПриемете входящо повикване.
CommunicateIncomingRejectОтхвърляне на входящо повикване.
CommunicateHFPCallStartЗапочнете телефонно обаждане чрез Bluetooth HFP.
CommunicateHFPCallEndПрекратете телефонно обаждане с Bluetooth HFP.
CommunicateContentStartЗапочнете поточно предаване на аудио съдържание към устройството.
CommunicateContentStopСпрете стрийминга на аудио съдържание.
SocketReceiveStatusПолучавайте актуализация на състоянието на WebSocket.

Аудио команди

Контролирайте силата на звука на високоговорителя, усилването на микрофона, аудио профилите и възпроизвеждането на текст в реч.

AudioPlayStorageВъзпроизвеждане на аудио файл от паметта на устройството.
AudioPlayContentВъзпроизвеждане на поточно аудио съдържание.
AudioSetVolumeЗадайте силата на звука на изхода на високоговорителя.

LED команди

Задайте цвят, яркост и анимационни модели на светодиода на индикаторната светлина на значката.

DeviceIlluminationSetЗадайте цвета на светодиода и режима на осветление.

Вътрешни команди

Вътрешни команди за изпращане, използвани за доставяне на контекст, история на канала, вокализация и аудио декодиране.

InternalSendContextИзпращане на контекстни данни към вътрешния манипулатор на контекст.
InternalSendChannelHistoryИзпращане на историята на канала до вътрешния обработчик.
InternalRequestVocalizationЗаявете вътрешно вокализиране на текст в реч.
InternalHandleVocalizationRTPОбработка на входящ RTP поток за вокализация.
InternalDecodeAudioДекодиране на входящ аудио поток.

Мобилни команди

Команди за координиране на значката със сдвоено мобилно приложение — push известия, синхронизиране на състоянието на приложението и дълбоко свързване.

MobileServiceStatusДокладване на състоянието на мобилната услуга на устройството. (Мобилни → Устройство)
MobileSocketOpenИнструктирайте мобилното приложение да отвори WebSocket връзка. (Устройство → Мобилно)
MobileSocketCloseИнструктирайте мобилното приложение да затвори WebSocket връзка. (Устройство → Мобилно)
MobileSocketStatusДокладване на състоянието на WebSocket на мобилното приложение. (Устройство → Мобилно)
MobileReceiveStatusДокладване на състоянието на получаване до мобилното приложение. (Устройство → Мобилно)
MobileSocketUpdateИзпращане на актуализация на данни от WebSocket до мобилното приложение. (Устройство → Мобилно)
MobilePTTStartУведомете мобилното приложение, че предаването на РТТ е започнало. (Устройство → Мобилно)
MobilePTTStopУведомете мобилното приложение, че предаването на РТТ е приключило. (Устройство → Мобилно)
MobileContextSetЗадайте контекстни данни в мобилното приложение. (Устройство → Мобилни устройства)
MobileEchoКоманда Echo за тестване на мобилната свързаност. (Устройство → Мобилно)

Готови ли сте да строите?

Присъединете се към общността на разработчиците на Connection и получете достъп до устройства с ограничен достъп, SDK и специализирана поддръжка.

Свържете се с нас