Platforma pro vývojáře

Stavějte na
Připojovací platforma

Dvě výkonná API – RESTful serverové API pro správu zařízení a orchestraci komunikace a nízkoúrovňový protokol CBBP pro přímou správu odznaků.

Referenční příručka k REST APIProtokol CBBP
OpenAPI 3.0JSON / RESTBluetooth + Wi-FiPodpora webhooku
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

Kompletní správa životního cyklu zařízení – zřizování, konfigurace, firmware, komunikace a analytika – přes standardní HTTPS.

Prozkoumejte REST API →

Protokol CBBP

Com Badge Basic Protocol — protokol příkazů JSON pro přímé ovládání zařízení přes Bluetooth (aplikace), WiFi (proxy server) nebo lokální dispečink.

Prozkoumejte CBBP →

Webhooky

Přihlaste se k odběru událostí zařízení v reálném čase – komunikace, změny stavu, aktualizace polohy – doručovaných jako datové části HTTP POST do vašeho koncového bodu.

Prozkoumejte webhooky →

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.

Začínáme

Ověřování

Rozhraní Connection API používá ověřování pomocí tokenu nosiče. Všechny požadavky musí v hlavičce autorizace obsahovat platný přístupový token JWT.

Získejte token

Odešlete své přihlašovací údaje do koncového bodu autorizace. Obdržíte krátkodobý access_token a delší refresh_token.

Použijte token

Zahrňte token do každého požadavku:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Žádost
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Odpověď 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Základní URL a verzování

Všechny koncové body API jsou verzovány pod /api/v1/. Základní URL závisí na vašem nasazení.

Pro nasazení hostovaná v cloudu použijte regionální koncový bod přiřazený vaší organizaci. Pro nasazení serveru v místní síti použijte název hostitele vašeho serveru.

ProstředíZákladní URL
Cloud (USA)https://beta.connection.app/api/v1
Místníhttps://<your-server>/api/v1
Typ obsahu
Všechna těla požadavků a odpovědí používají application/json. U požadavků s tělem uveďte Content-Type: application/json.

Chyby a stavové kódy

API používá standardní stavové kódy HTTP. Chybové odpovědi zahrnují strojově čitelný kód a zprávu čitelnou člověkem.

PostaveníVýznam
200Úspěch
201Vytvořeno
400Špatný požadavek – neplatné parametry
401Neoprávněné – chybějící nebo vypršelý token
403Zakázáno – nedostatečná oprávnění
404Nenalezeno
500Interní chyba serveru
Reakce na chybu
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
REST API

Přehled REST API

Rozhraní REST API serveru Connection Server poskytuje plný programový přístup k vaší flotile zařízení, komunikační infrastruktuře a analytickým nástrojům. Dodržuje konvence RESTful s těly požadavků/odpovědí JSON.

Ověřování API
Uživatelé
Zařízení
Kanály
Sdělení
Zvukový most
Konverzace
Obsah
Lokality
Push notifikace
Skladování
Hromadné operace
Datum a čas

Ověřování

Ověřování na základě tokenů. Přihlášení vrací token, který musí být odeslán jako Autorizace: Token.<token> na všechny následné žádosti.

POST/api/v1/loginOvěření uživatele a přijetí autorizačního tokenu
POST/api/v1/login-deviceOvěření zařízení pomocí UUID a MAC adresy
POST/api/v1/logoutZrušit platnost aktuálního tokenu relace

Uživatelé

Vytváření a správa uživatelských účtů. Koncový bod GET /users/user vrací aktuálně ověřeného uživatele.

GET/api/v1/users/userNačíst profil aktuálně přihlášeného uživatele
POST/api/v1/users/userVytvořte nový uživatelský účet
PATCH/api/v1/users/user/{uuid}Aktualizovat uživatelský profil (např. profilový obrázek)

Zařízení

Zobrazovat a kontrolovat zařízení, spravovat přidružení uživatelů k zařízením, číst a zapisovat nastavení a stav jednotlivých zařízení, spravovat obrazy firmwaru a úložiště a přijímat protokoly a zprávy o selhání.

GET/api/v1/devices/deviceSeznam všech zařízení
GET/api/v1/devices/device/{uuid}Získejte podrobné informace o zařízení včetně firmwaru a nastavení
PUT/api/v1/devices/association/{uuid}Aktualizace přidružení mezi uživatelem a zařízením
DELETE/api/v1/devices/association/{uuid}Odebrat přidružení uživatele k zařízení a uložená nastavení
GET/api/v1/devices/device/{device_uuid}/settingsSeznam nastavení uložených pro zařízení
POST/api/v1/devices/device/{device_uuid}/settingsUložit nastavení specifická pro zařízení
GET/api/v1/devices/device/{device_uuid}/statusZískání stavu zařízení (připojení, baterie, senzory, stav zvuku)
POST/api/v1/devices/device/{device_uuid}/statusOdeslat stav zařízení ze zařízení
GET/api/v1/devices/device/{device_uuid}/contextVypsat kontextové hodnoty uložené pro zařízení
POST/api/v1/devices/device/{device_uuid}/ingest-contextPřijímání kontextu GPS a WiFi ze zařízení
GET/api/v1/devices/firmwareVypsat verze firmwaru kompatibilní s danou verzí hardwaru/softwaru
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchNačíst obraz firmwaru po částech
GET/api/v1/devices/languageSeznam podporovaných jazyků a hlasů zařízení
GET/api/v1/devices/storage_imageStáhnout vlastní obraz úložiště zařízení pro dané národní prostředí
POST/api/v1/devices/logPřijmout soubor protokolu ze zařízení
POST/api/v1/devices/crashPřijetí výpisu jádra ze zařízení
PATCH/api/v1/devices/crash/{uuid}Aktualizace záznamu o havárii

Proxy CBBP

Odešlete libovolný příkaz CBBP do zařízení prostřednictvím serveru. Server předává příkaz přes WiFi připojení zařízení a vrací odpověď zařízení. Odchozí odpověď make také obsahuje zprávu CBBPMessage, kterou zařízení okamžitě provede.

POST/api/v1/devices/device/{device_uuid}/cbbpOdeslání příkazu CBBP do zařízení přes server
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Načíst stav a odpověď dříve odeslaného příkazu CBBP

Tělo požadavku je obálka příkazu CBBP. Uložený objekt CBBPCommand sleduje stav doručení: NENASTAVENO → ODESLANO → PŘIJATO nebo VYPRŠELO DORUČENÍ.

Pro kontrolu, zda zařízení příkaz přijalo a odpovědělo na něj, se použije příkaz GET /cbbp/.
Žádost — odchozí zpráva
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Odpověď — Stav příkazu CBBPCommand
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Kanály

Kanály jsou základní komunikační primitiva. Mezi typy patří ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService a ChannelRecorder.

GET/api/v1/channels/channelSeznam kanálů, volitelně filtrovaných podle typu_objektu
POST/api/v1/channels/channelVytvoření kanálu (ChannelGroup, ChannelContact nebo ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Aktualizace skupiny kanálů nebo kontaktu kanálů
DELETE/api/v1/channels/channel/{uuid}Smazání kanálu
DELETE/api/v1/channels/{uuid}Odstranění skupiny kanálů
DELETE/api/v1/channels/by-type/{channelType}Smazat všechny kanály daného typu (aktuálně ChannelContact)
GET/api/v1/channels/associationZobrazit seznam přidružených kanálů pro aktuálního uživatele
POST/api/v1/channels/associationŽádost o přidružení ke kanálu
PATCH/api/v1/channels/association/{uuid}Přijmout, odmítnout nebo aktualizovat nastavení přidružení
DELETE/api/v1/channels/association/{uuid}Odebrání přidružení ke kanálu
GET/api/v1/channels/historyZískání historie stránkovaného přístupu ke kanálu pro aktuálního uživatele
POST/api/v1/channels/historyVytvořte záznam v historii kanálu
GET/api/v1/channels/searchVyhledávání kanálů podle řetězce dotazu a volitelného filtru typu

Sdělení

Zahájení a správa aktivních komunikačních relací – odchozí hovory, VCP, nahrávání a streamování obsahu. Odpověď typu outgoing-make obsahuje zprávu CBBPMessage, na kterou zařízení okamžitě reaguje.

POST/api/v1/communicate/outgoing-makeZahájit odchozí kanál pro ChannelPeople, ChannelGroup, ChannelContact nebo ChannelContactNumber
POST/api/v1/communicate/incoming-acceptancePřijmout nebo odmítnout příchozí žádost o připojení ke kanálu
POST/api/v1/communicate/closeZavření aktuálně aktivního komunikačního kanálu na zařízení
POST/api/v1/communicate/vcp-activateInicializace protokolu VCP (Voice Communication Protocol) na serveru a zařízení
POST/api/v1/communicate/vcp-deactivateDeaktivace VCP, návrat na jakýkoli předchozí kanál
POST/api/v1/communicate/recording-activateAktivujte režim nahrávání na serveru a zařízení
POST/api/v1/communicate/content-startOtevření streamovacího kanálu pro audio obsah
POST/api/v1/communicate/request-vocalizationGenerování zvuku TTS pro daný text, volitelně jeho překlad

Zvukový most

Přístup k nahraným konverzacím v rámci přemosťování včetně kompletních přepisů, seznamů účastníků a shrnutí generovaných umělou inteligencí. Podporuje více šablon shrnutí (poznámky ze schůzek, poznámky z hodin, zdravotní péče atd.) a generování zvuku TTS pro shrnutí.

GET/api/v1/bridge/conversationsVypsat všechny konverzace v mostě
GET/api/v1/bridge/conversations/{uuid}Získejte podrobný rozhovor včetně přepisu, účastníků a shrnutí
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenerování shrnutí konverzace pomocí umělé inteligence
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenerování zvuku pro shrnutí konverzace

Konverzace

Konverzační relace s umělou inteligencí využívající ChatGPT, Gemini nebo nativní engine. Podporuje více person (lékař, lektor, mechanik atd.) a stránkovanou historii zpráv.

GET/api/v1/conversations/conversationSeznam relací generátoru umělé inteligence, filtrovatelných podle osoby a nástroje
POST/api/v1/conversations/conversationVytvoření nové relace konverzace s umělou inteligencí
GET/api/v1/conversations/conversation/{uuid}Načíst konverzační relaci s volitelným shrnutím/aktualizací o nepřítomnosti
DELETE/api/v1/conversations/conversation/{uuid}Smazání konverzační relace
GET/api/v1/conversations/conversation/{uuid}/messagesSeznam zpráv v konverzaci
POST/api/v1/conversations/conversation/{uuid}/messagesPřidejte uživatelskou zprávu a obdržte odpověď od umělé inteligence

Obsah

Procházejte a přehrávejte streamovaný audio obsah na zařízeních. Obsah je uspořádán do stromu kategorií; oblíbený obsah lze filtrovat podle města, regionu nebo země.

GET/api/v1/content/categoriesZískejte strom kategorií obsahu
GET/api/v1/content/contentZobrazit dostupný obsah v rámci kategorie
GET/api/v1/content/popularUveďte oblíbený obsah pro dané město, region nebo zemi

Lokality

Převede zeměpisné souřadnice na strukturovaný objekt města, regionu a země. Používá se zařízeními při načítání kontextu.

POST/api/v1/location/determineUrčit zeměpisnou šířku/délku na město, region a zemi

Push notifikace

Zaregistrujte si mobilní aplikaci pro příjem push notifikací FCM. Podporuje iOS, Android a webové aplikace.

POST/api/v1/push-notifications/pushZaregistrujte si mobilní aplikaci pro push notifikace FCM (iOS, Android, web)

Skladování

Stáhnout soubory uložené v objektech modelu a spustit odstranění pozadí obrázku (vrací výsledek kódovaný v base64).

GET/api/v1/storage/retrieve/{path}Stažení uloženého souboru podle cesty
POST/api/v1/storage/remove-backgroundOdstraní pozadí z obrázku (vrací base64)

Hromadné operace

Spusťte více operací API v jednom HTTP požadavku. Zadejte single_transaction=true, chcete-li všechny operace zabalit do jedné atomické transakce – selhání jakékoli položky vrátí celou dávku zpět.

POST/api/v1/bulkSpuštění více operací API v jednom požadavku, volitelně jako jedna atomická transakce

Datum a čas

Vrací aktuální datum a čas serveru v GMT+0. Nevyžaduje ověřování. Používá se zařízeními k synchronizaci jejich interních hodin.

GET/api/v1/current-datetimeVrátí aktuální datum a čas v GMT+0
Protokol CBBP

Základní protokol Com Badge

CBBP je odlehčený protokol JSON pro přímou interakci s odznaky Connection. Poskytuje vám plnou kontrolu nad všemi hardwarovými a softwarovými funkcemi v zařízení.

Formát zprávy

Každá interakce CBBP se skládá z příkazové zprávy odeslané do zařízení a výsledné zprávy vrácené zařízením.

Pole objektu v požadavku i odpovědi obsahuje data specifická pro příkaz a může být vynecháno, pokud není potřeba.

Kompletní dokumentace protokolu je k dispozici registrovaným partnerům. Kontaktujte svého obchodního zástupce společnosti Connection nebo nás kontaktujte developer@connectionbadge.com požádat o přístup ke kompletní referenční dokumentaci k příkazům CBBP, včetně kompletních schémat požadavků/odpovědí, chybových kódů a integračních průvodců.
Příkazová zpráva
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Výsledná zpráva
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Doprava

Zprávy CBBP lze doručit na odznak třemi různými transporty v závislosti na vaší integrační architektuře.

Bluetooth (aplikace)

Odesílejte příkazy CBBP přímo z mobilní aplikace přes BLE. Vyžaduje, aby bylo zařízení spárované a v dosahu.

Mobilní SDK

WiFi nebo Bluetooth přes server

Proxy CBBP přes REST API — POST /devices//cbbp. Server automaticky směruje na zařízení přes WiFi nebo Bluetooth v závislosti na tom, jak je odznak připojen. Nejběžnější pro backendové integrace.

REST API

Interní expedice

Odesílání CBBP na zařízení nebo mezi procesy. Používá se firmwarem odznaku ke směrování příkazů mezi interními subsystémy.

Pouze firmware

Příkazy pro napájení

Ovládání stavu napájení zařízení – režim spánku, probuzení, restart a obnovení továrního nastavení.

PowerRebootOkamžitě restartujte zařízení.
PowerDeepsleepPřejděte do režimu hlubokého spánku (nízká spotřeba energie).
FactoryResetVymažte veškerou konfiguraci a obnovte tovární nastavení.

Příkazy WiFi

Konfigurujte bezdrátové sítě, vyhledávejte přístupové body, kontrolujte stav připojení a spravujte uložené přihlašovací údaje.

WiFiScanVyhledejte dostupné přístupové body WiFi.
WiFiAPTestOtestujte připojení ke konkrétnímu přístupovému bodu WiFi.
WiFiAPJoinPřipojte se k přístupovému bodu WiFi pomocí poskytnutých přihlašovacích údajů.

Příkazy Bluetooth

Ovládejte reklamu BLE, párování a komunikaci mezi odznaky.

BTScanBTVyhledejte klasická zařízení Bluetooth.
BTScanBLEVyhledejte zařízení BLE.
DeviceBLEServiceAvailableOznačte službu BLE jako dostupnou.
DeviceBLEServiceUnavailableOznačte službu BLE jako nedostupnou.
DeviceBLEActiveNastavte rádio BLE do aktivního stavu.
DeviceBLEIdleNastavte rádio BLE do klidového stavu.
DeviceBLEAdvChannelAddPřidejte kanál do reklamní datové části BLE.
DeviceBTScanSpusťte vyhledávání zařízení Bluetooth.
DeviceBTA2DStartSpusťte streamování zvuku přes Bluetooth A2DP.
DeviceBTA2DEndUkončení streamování zvuku přes Bluetooth A2DP.
DeviceBTNativeAssistStartSpusťte nativní hlasový asistent Bluetooth.
DeviceBTNativeAssistEndUkončete nativního hlasového asistenta Bluetooth.

Příkazy nastavení

Čtení a zápis konfigurace zařízení – zobrazovaný název, časové pásmo, jazyk a příznaky funkcí.

SettingsListGetNačíst všechna nastavení jako seznam klíč-hodnota.
SettingsListSetZapište více hodnot nastavení najednou.
SettingsGetZískejte hodnotu jednoho nastavení pomocí klíče.
SettingsSetNastavte hodnotu jednoho nastavení.
SettingsSendOdeslat aktuální nastavení na server.
SettingsClearVymazat konkrétní hodnoty nastavení.
SettingsEraseVymazat všechna uložená nastavení.

Příkazy firmwaru

Spouštění aktualizací firmwaru OTA, kontrola stavu aktualizací a dotazování se na aktuální verzi firmwaru v zařízení.

FirmwareCheckZkontrolujte, zda je k dispozici aktualizace firmwaru.
FirmwareUpdateSpusťte aktualizaci firmwaru OTA.
FirmwareValidateOvěřte integritu staženého obrazu firmwaru.

Příkazy zařízení

Životní cyklus zařízení, ověřování, konfigurace, protokolování, stav a správa hardwaru.

NoOpBez provozu / udržování v provozu.
TestZákladní test konektivity.
DeviceDateTimeZískání nebo nastavení data a času zařízení.
DeviceAuthenticateOvěřte zařízení na serveru.
DeviceConfigureAplikujte na zařízení konfigurační datovou část.
DevicePostConnectionTasksSpusťte úlohy inicializace po připojení.
DeviceStorageLoadNačíst data z úložiště v zařízení.
DeviceLoadCustomAudioNahrajte do zařízení vlastní zvukové soubory.
DeviceCoredumpSendNahrajte na server výpis jádra havárie.
DeviceAttachPřipojte zařízení k relaci serveru.
DeviceDetachOdpojte zařízení od relace serveru.
DeviceLogSendNahrajte protokoly zařízení na server.
DeviceConnectionTestOtestujte připojení k serveru.
DeviceStatusSendOdeslat stav zařízení na server.
DeviceStatusGetZískejte aktuální stav zařízení.
DeviceInteractionSpustit událost interakce zařízení.
DeviceSetAPIHostNastavte hostitele serveru API.
DeviceTestMicsSpusťte autotest mikrofonu.
HardwareI2CCommandOdešlete nezpracovaný příkaz I2C do hardwarové periferie.

Komunikační příkazy

Zahájejte hovory, odesílejte zprávy, spravujte aktivní komunikační relace a ovládejte nahrávání.

CommunicateChannelJoinPřipojte se ke komunikačnímu kanálu.
CommunicateChannelLeaveZanechte komunikační kanál.
CommunicateChannelChangePřepněte na jiný kanál.
CommunicateChannelCloseUzavření komunikačního kanálu.
CommunicateReceiveIncomingUpozornit zařízení na příchozí komunikaci.
CommunicateRequestOutgoingPožádejte o odchozí komunikaci.
CommunicateVCPActivateAktivujte relaci protokolu Voice Communication Protocol.
CommunicateVCPDeactivateDeaktivujte relaci VCP.
CommunicateRecordingActivateZačněte nahrávat aktivní komunikaci.
CommunicateIncomingAcceptPřijmout příchozí hovor.
CommunicateIncomingRejectOdmítnout příchozí hovor.
CommunicateHFPCallStartZahajte telefonní hovor přes Bluetooth HFP.
CommunicateHFPCallEndUkončete telefonní hovor přes Bluetooth HFP.
CommunicateContentStartZačněte streamovat zvukový obsah do zařízení.
CommunicateContentStopZastavte streamování zvukového obsahu.
SocketReceiveStatusDostávat aktualizaci stavu WebSocketu.

Zvukové příkazy

Ovládejte hlasitost reproduktoru, zesílení mikrofonu, zvukové profily a přehrávání textu na řeč.

AudioPlayStoragePřehrajte zvukový soubor z úložiště v zařízení.
AudioPlayContentPřehrávání streamovaného zvukového obsahu.
AudioSetVolumeNastavte hlasitost výstupu reproduktoru.

Příkazy LED diod

Nastavte barvu LED, jas a animační vzory na kontrolce odznaku.

DeviceIlluminationSetNastavte barvu LED a vzor podsvícení.

Interní příkazy

Interní dispečerské příkazy používané pro doručování kontextu, historii kanálu, vokalizaci a dekódování zvuku.

InternalSendContextOdešle kontextová data internímu obslužnému programu kontextu.
InternalSendChannelHistoryOdeslat historii kanálu internímu obslužnému programu.
InternalRequestVocalizationInterně požádat o vokalizaci převodu textu na řeč.
InternalHandleVocalizationRTPZpracování příchozího RTP streamu vokalizace.
InternalDecodeAudioDekódování příchozího zvukového streamu.

Mobilní příkazy

Příkazy pro koordinaci odznaku se spárovanou mobilní aplikací – push notifikace, synchronizace stavu aplikace a deep linking.

MobileServiceStatusHlásit stav mobilního připojení do zařízení. (Mobil → Zařízení)
MobileSocketOpenPokyn mobilní aplikaci k otevření připojení WebSocket. (Zařízení → Mobilní zařízení)
MobileSocketClosePokyn mobilní aplikaci k ukončení připojení WebSocket. (Zařízení → Mobilní zařízení)
MobileSocketStatusHlásit stav WebSocketu do mobilní aplikace. (Zařízení → Mobilní zařízení)
MobileReceiveStatusHlásit stav příjmu do mobilní aplikace. (Zařízení → Mobilní)
MobileSocketUpdateOdeslat aktualizaci dat WebSocket do mobilní aplikace. (Zařízení → Mobilní zařízení)
MobilePTTStartUpozorněte mobilní aplikaci, že byl zahájen přenos PTT. (Zařízení → Mobilní zařízení)
MobilePTTStopUpozornit mobilní aplikaci na ukončení přenosu PTT. (Zařízení → Mobilní zařízení)
MobileContextSetNastavení kontextových dat v mobilní aplikaci. (Zařízení → Mobilní zařízení)
MobileEchoPříkaz Echo pro testování mobilního připojení. (Zařízení → Mobilní zařízení)

Připraveni stavět?

Připojte se k vývojářské komunitě Connection a získejte přístup k zařízením sandbox, sadám SDK a specializované podpoře.

Kontaktujte nás