Utvecklarplattform

Bygg vidare på
Anslutningsplattform

Två kraftfulla API:er – ett RESTful-server-API för enhetshantering och kommunikationsorkestrering, och ett lågnivå-CBBP-protokoll för direkt märkeskontroll.

REST API-referensCBBP-protokollet
OpenAPI 3.0JSON / RESTBluetooth + WiFiWebhook-stöd
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

Fullständig hantering av enhetens livscykel – provisionering, konfiguration, firmware, kommunikation och analys – via standard HTTPS.

Utforska REST API →

CBBP-protokollet

Com Badge Basic Protocol — ett JSON-kommandoprotokoll för direkt enhetskontroll via Bluetooth (app), WiFi (serverproxy) eller lokal dispatch.

Utforska CBBP →

Webhooks

Prenumerera på enhetshändelser i realtid – kommunikation, statusändringar, platsuppdateringar – levererade som HTTP POST-nyttolaster till din slutpunkt.

Utforska Webhooks →

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.

Komma igång

Autentisering

Anslutnings-API:et använder Bearer-tokenautentisering. Alla förfrågningar måste innehålla en giltig JWT-åtkomsttoken i Auktoriseringsrubriken.

Skaffa en token

SKICKA dina inloggningsuppgifter till autentiseringsslutpunkten. Du får en kortlivad access_token och en längrelivad refresh_token.

Använd tokenet

Inkludera token i varje förfrågan:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Begäran
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Svar 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Bas-URL och versionshantering

Alla API-slutpunkter är versionsstyrda under /api/v1/. Bas-URL:en beror på din distribution.

För molnbaserade distributioner, använd den regionala slutpunkt som tilldelats din organisation. För lokala serverdistributioner, använd din servers värdnamn.

MiljöBas-URL
Moln (USA)https://beta.connection.app/api/v1
Lokalthttps://<your-server>/api/v1
Innehållstyp
Alla förfrågnings- och svarstexter använder application/json. Inkludera Content-Type: application/json på förfrågningar med en text.

Fel och statuskoder

API:et använder standard HTTP-statuskoder. Felsvar inkluderar maskinläsbar kod och ett människoläsbart meddelande.

StatusMenande
200Framgång
201Skapad
400Felaktig begäran — ogiltiga parametrar
401Obehörig — saknad eller utgången token
403Förbjudet — otillräckliga behörigheter
404Inte hittad
500Internt serverfel
Felrespons
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
REST API

Översikt över REST API

Connection Server REST API ger fullständig programmatisk åtkomst till din enhetsflotta, kommunikationsinfrastruktur och analys. Det följer RESTful-konventioner med JSON-förfrågnings-/svarsinnehåll.

API-autentisering
Användare
Enheter
Kanaler
Kommunikation
Ljudbrygga
Konversationer
Innehåll
Platser
Push-meddelanden
Lagring
Massoperationer
Datum och tid

Autentisering

Tokenbaserad autentisering. Inloggning returnerar en token som måste skickas som Auktorisering: Token<token> på alla efterföljande förfrågningar.

POST/api/v1/loginAutentisera en användare och få en autentiseringstoken
POST/api/v1/login-deviceAutentisera en enhet med UUID och MAC-adress
POST/api/v1/logoutOgiltigförklara den aktuella sessionstoken

Användare

Skapa och hantera användarkonton. GET /users/user-slutpunkten returnerar den för närvarande autentiserade användaren.

GET/api/v1/users/userHämta den för närvarande inloggade användarprofilen
POST/api/v1/users/userSkapa ett nytt användarkonto
PATCH/api/v1/users/user/{uuid}Uppdatera användarprofil (t.ex. profilbild)

Enheter

Lista och inspektera enheter, hantera kopplingar mellan användare och enheter, läs och skriv inställningar och status per enhet, hantera firmware och lagringsavbildningar samt ta emot loggar och kraschrapporter.

GET/api/v1/devices/deviceLista alla enheter
GET/api/v1/devices/device/{uuid}Få detaljerad enhetsinformation inklusive firmware och inställningar
PUT/api/v1/devices/association/{uuid}Uppdatera kopplingen mellan en användare och en enhet
DELETE/api/v1/devices/association/{uuid}Ta bort koppling mellan användare och enhet och lagrade inställningar
GET/api/v1/devices/device/{device_uuid}/settingsLista inställningar som lagrats för en enhet
POST/api/v1/devices/device/{device_uuid}/settingsSpara enhetsspecifika inställningar
GET/api/v1/devices/device/{device_uuid}/statusHämta enhetsstatus (anslutning, batteri, sensorer, ljudstatus)
POST/api/v1/devices/device/{device_uuid}/statusPublicera enhetsstatus från enheten
GET/api/v1/devices/device/{device_uuid}/contextLista kontextvärden som lagrats för en enhet
POST/api/v1/devices/device/{device_uuid}/ingest-contextTa emot GPS + WiFi-kontext från enheten
GET/api/v1/devices/firmwareLista firmware-versioner som är kompatibla med en given hårdvaru-/programvaruversion
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchHämta en firmware-avbildning i bitar
GET/api/v1/devices/languageLista enhetsspråk och röster som stöds
GET/api/v1/devices/storage_imageLadda ner anpassad enhetslagringsavbildning för en språkinställning
POST/api/v1/devices/logTa emot en loggfil från en enhet
POST/api/v1/devices/crashTa emot en kärndump från en enhet
PATCH/api/v1/devices/crash/{uuid}Uppdatera en kraschpost

CBBP-proxy

Skicka valfritt CBBP-kommando till en enhet via servern. Servern vidarebefordrar kommandot via enhetens WiFi-anslutning och returnerar enhetens svar. Det utgående make-svaret bäddar också in ett CBBPMeddelande som enheten kör omedelbart.

POST/api/v1/devices/device/{device_uuid}/cbbpSkicka ett CBBP-kommando till en enhet via servern
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Hämta status och svar på ett tidigare skickat CBBP-kommando

Begäran är ett CBBP-kommandokuvert. Det lagrade CBBPCommand-objektet spårar leveransstatus: UNSET → SENT → RECEIVED eller TIMED_OUT.

Kör GET /cbbp/ för att kontrollera om enheten tog emot och svarade på kommandot.
Begäran — utgående meddelande
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Svar — CBBP-kommandostatus
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Kanaler

Kanaler är de centrala kommunikationsprimitiverna. Typerna inkluderar ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService och ChannelRecorder.

GET/api/v1/channels/channelLista kanaler, valfritt filtrerade efter objekttyp
POST/api/v1/channels/channelSkapa en kanal (ChannelGroup, ChannelContact eller ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Uppdatera en kanalgrupp eller kanalkontakt
DELETE/api/v1/channels/channel/{uuid}Ta bort en kanal
DELETE/api/v1/channels/{uuid}Ta bort en kanalgrupp
DELETE/api/v1/channels/by-type/{channelType}Ta bort alla kanaler av en given typ (för närvarande Kanalkontakt)
GET/api/v1/channels/associationLista kanalassociationer för den aktuella användaren
POST/api/v1/channels/associationBegär en koppling till en kanal
PATCH/api/v1/channels/association/{uuid}Godkänn, avböj eller uppdatera associationsinställningar
DELETE/api/v1/channels/association/{uuid}Ta bort en koppling till en kanal
GET/api/v1/channels/historyHämta paginerad kanalåtkomsthistorik för den aktuella användaren
POST/api/v1/channels/historySkapa en kanalhistorikpost
GET/api/v1/channels/searchSök kanaler efter frågesträng och valfritt typfilter

Kommunikation

Initiera och hantera aktiva kommunikationssessioner – utgående samtal, VCP, inspelning och innehållsströmning. Svaret på utgående samtal inkluderar ett CBBPMeddelande som enheten omedelbart reagerar på.

POST/api/v1/communicate/outgoing-makeInitiera en utgående kanal till en kanalperson, kanalgrupp, kanalkontakt eller kanalkontaktnummer
POST/api/v1/communicate/incoming-acceptanceAcceptera eller avböja en inkommande begäran om kanalanslutning
POST/api/v1/communicate/closeStäng den aktiva kommunikationskanalen på en enhet
POST/api/v1/communicate/vcp-activateInitiera Voice Communication Protocol (VCP) på servern och enheten
POST/api/v1/communicate/vcp-deactivateAvaktivera VCP, återgå till valfri föregående kanal
POST/api/v1/communicate/recording-activateAktivera inspelningsläge på servern och enheten
POST/api/v1/communicate/content-startÖppna en streamingkanal för ljudinnehåll
POST/api/v1/communicate/request-vocalizationGenerera TTS-ljud för den givna texten, eventuellt översätta den

Ljudbrygga

Få tillgång till inspelade bryggsamtal inklusive fullständiga transkriptioner, deltagarlistor och AI-genererade sammanfattningar. Stöder flera sammanfattningsmallar (mötesanteckningar, klassanteckningar, hälsovård etc.) och TTS-ljudgenerering för sammanfattningar.

GET/api/v1/bridge/conversationsLista alla bridgekonversationer
GET/api/v1/bridge/conversations/{uuid}Få en detaljerad konversation inklusive transkription, deltagare och sammanfattning
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenerera en AI-sammanfattning för en konversation
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenerera ljud för en konversationssammanfattning

Konversationer

AI-drivna konversationssessioner med ChatGPT, Gemini eller den inbyggda sökmotorn. Stöder flera personas (läkare, handledare, mekaniker etc.) och paginerad meddelandehistorik.

GET/api/v1/conversations/conversationLista AI-generatorsessioner, filtrerbara efter persona och verktyg
POST/api/v1/conversations/conversationSkapa en ny AI-konversationssession
GET/api/v1/conversations/conversation/{uuid}Hämta en konversationssession med valfri sammanfattning/uppdatering frånvaro
DELETE/api/v1/conversations/conversation/{uuid}Ta bort en konversationssession
GET/api/v1/conversations/conversation/{uuid}/messagesLista meddelanden i en konversation
POST/api/v1/conversations/conversation/{uuid}/messagesLägg till ett användarmeddelande och få ett AI-svar

Innehåll

Bläddra bland och spela upp strömmande ljudinnehåll på enheter. Innehållet är organiserat i ett kategoriträd; populärt innehåll kan filtreras efter stad, region eller land.

GET/api/v1/content/categoriesHämta ett träd med innehållskategorier
GET/api/v1/content/contentLista tillgängligt innehåll inom en kategori
GET/api/v1/content/popularLista populärt innehåll för en given stad, region eller land

Platser

Lös geografiska koordinater till ett strukturerat objekt för stad, region och land. Används av enheter vid inmatning av kontext.

POST/api/v1/location/determineLös upp en latitud/longitud till stad, region och land

Push-meddelanden

Registrera en mobilapp för att ta emot FCM push-meddelanden. Stöder iOS, Android och webbmål.

POST/api/v1/push-notifications/pushRegistrera en mobilapp för FCM push-meddelanden (iOS, Android, webb)

Lagring

Ladda ner filer som lagrats på modellobjekt och kör borttagning av bildbakgrund (returnerar base64-kodat resultat).

GET/api/v1/storage/retrieve/{path}Ladda ner en lagrad fil via sökväg
POST/api/v1/storage/remove-backgroundTa bort bakgrunden från en bild (returnerar base64)

Massoperationer

Kör flera API-operationer i en enda HTTP-begäran. Skicka single_transaction=true för att slå in alla operationer i en atomär transaktion — ett fel på ett objekt återställer hela batchen.

POST/api/v1/bulkKör flera API-operationer i en enda begäran, valfritt som en enda atomtransaktion

Datum och tid

Returnerar aktuell serverdatum och tid i GMT+0. Kräver inte autentisering. Används av enheter för att synkronisera sin interna klocka.

GET/api/v1/current-datetimeReturnera aktuellt datum och tid i GMT+0
CBBP-protokollet

Grundprotokoll för Com Badge

CBBP är ett lättviktigt JSON-kommandoprotokoll för direkt interaktion med anslutningsmärken. Det ger dig full kontroll över alla hårdvaru- och mjukvarufunktioner på enheten.

Meddelandeformat

Varje CBBP-interaktion består av ett kommandomeddelande som skickas till enheten och ett resultatmeddelande som returneras av enheten.

Objektfältet i både begäran och svar innehåller kommandospecifik data och kan utelämnas när det inte behövs.

Fullständig protokolldokumentation är tillgänglig för registrerade partners. Kontakta din Connection-representant eller kontakta developer@connectionbadge.com för att begära åtkomst till den fullständiga CBBP-kommandoreferensen, inklusive fullständiga begäran-/svarsscheman, felkoder och integrationsguider.
Kommandomeddelande
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Resultatmeddelande
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transport

CBBP-meddelanden kan levereras till en bricka via tre olika transporter beroende på din integrationsarkitektur.

Bluetooth (App)

Skicka CBBP-kommandon direkt från en mobilapp via BLE. Kräver att enheten är parad ihop och inom räckhåll.

Mobil SDK

WiFi eller Bluetooth via servern

Proxy CBBP via REST API — POST /devices//cbbp. Servern dirigerar automatiskt till enheten via WiFi eller Bluetooth beroende på hur märket är anslutet. Vanligast för backend-integrationer.

REST API

Intern utskick

CBBP-utskick på enheten eller mellan processer. Används av badge-firmwaren för att dirigera kommandon mellan interna delsystem.

Endast firmware

Power Commands

Styr enhetens strömstatus — viloläge, väckning, omstart och fabriksåterställning.

PowerRebootStarta om enheten omedelbart.
PowerDeepsleepGå in i djupt viloläge (låg strömförbrukning).
FactoryResetRadera all konfiguration och återställ till fabriksinställningarna.

WiFi-kommandon

Konfigurera trådlösa nätverk, skanna efter accesspunkter, kontrollera anslutningsstatus och hantera sparade inloggningsuppgifter.

WiFiScanSkanna efter tillgängliga WiFi-åtkomstpunkter.
WiFiAPTestTesta anslutningen till en specifik WiFi-åtkomstpunkt.
WiFiAPJoinAnslut till en WiFi-åtkomstpunkt med de angivna inloggningsuppgifterna.

Bluetooth-kommandon

Styr BLE-annonsering, parkoppling och kommunikation mellan märken.

BTScanBTSkanna efter klassiska Bluetooth-enheter.
BTScanBLESkanna efter BLE-enheter.
DeviceBLEServiceAvailableMarkera BLE-tjänsten som tillgänglig.
DeviceBLEServiceUnavailableMarkera BLE-tjänsten som otillgänglig.
DeviceBLEActiveStäll in BLE-radion i aktivt läge.
DeviceBLEIdleStäll in BLE-radion i viloläge.
DeviceBLEAdvChannelAddLägg till en kanal i BLE-annonseringsnyttolasten.
DeviceBTScanStarta en Bluetooth-enhetssökning.
DeviceBTA2DStartStarta Bluetooth A2DP-ljudströmning.
DeviceBTA2DEndAvsluta Bluetooth A2DP-ljudströmning.
DeviceBTNativeAssistStartStarta den inbyggda Bluetooth-röstassistenten.
DeviceBTNativeAssistEndAvsluta den inbyggda Bluetooth-röstassistenten.

Inställningskommandon

Läs och skriv enhetskonfiguration — visningsnamn, tidszon, språk och funktionsflaggor.

SettingsListGetHämta alla inställningar som en nyckel-värde-lista.
SettingsListSetSkriv flera inställningsvärden samtidigt.
SettingsGetHämta värdet för en enskild inställning med hjälp av nyckel.
SettingsSetStäll in värdet för en enskild inställning.
SettingsSendSkicka aktuella inställningar till servern.
SettingsClearRensa specifika inställningsvärden.
SettingsEraseRadera alla lagrade inställningar.

Firmware-kommandon

Utlös OTA-uppdateringar av firmware, kontrollera uppdateringsstatus och fråga efter den aktuella firmwareversionen på enheten.

FirmwareCheckKontrollera om en firmware-uppdatering är tillgänglig.
FirmwareUpdateStarta en OTA-uppdatering av den inbyggda programvaran.
FirmwareValidateValidera integriteten för en nedladdad firmware-avbildning.

Enhetskommandon

Enhetens livscykel, autentisering, konfiguration, loggning, status och hårdvarukontroll.

NoOpIngen drift / keep-live.
TestGrundläggande anslutningstest.
DeviceDateTimeHämta eller ställ in enhetens datum och tid.
DeviceAuthenticateAutentisera enheten med servern.
DeviceConfigureTillämpa en konfigurationsnyttolast på enheten.
DevicePostConnectionTasksKör initialiseringsuppgifter efter anslutning.
DeviceStorageLoadLadda data från enhetens lagring.
DeviceLoadCustomAudioLadda in anpassade ljudfiler på enheten.
DeviceCoredumpSendLadda upp en kraschkärndump till servern.
DeviceAttachAnslut enheten till en serversession.
DeviceDetachKoppla bort enheten från en serversession.
DeviceLogSendLadda upp enhetsloggar till servern.
DeviceConnectionTestTesta serveranslutningen.
DeviceStatusSendSkicka enhetsstatus till servern.
DeviceStatusGetHämta aktuell enhetsstatus.
DeviceInteractionUtlös en enhetsinteraktionshändelse.
DeviceSetAPIHostAnge API-servervärden.
DeviceTestMicsKör ett självtest av mikrofonen.
HardwareI2CCommandSkicka ett rått I2C-kommando till en hårdvarukringutrustning.

Kommunikationskommandon

Ring samtal, skicka meddelanden, hantera aktiva kommunikationssessioner och styr inspelning.

CommunicateChannelJoinGå med i en kommunikationskanal.
CommunicateChannelLeaveLämna en kommunikationskanal.
CommunicateChannelChangeByt till en annan kanal.
CommunicateChannelCloseStäng en kommunikationskanal.
CommunicateReceiveIncomingMeddela enheten om inkommande kommunikation.
CommunicateRequestOutgoingBegär utgående kommunikation.
CommunicateVCPActivateAktivera röstkommunikationsprotokollsessionen.
CommunicateVCPDeactivateInaktivera VCP-sessionen.
CommunicateRecordingActivateBörja spela in den aktiva kommunikationen.
CommunicateIncomingAcceptTa emot ett inkommande samtal.
CommunicateIncomingRejectAvvisa ett inkommande samtal.
CommunicateHFPCallStartStarta ett Bluetooth HFP-telefonsamtal.
CommunicateHFPCallEndAvsluta ett Bluetooth HFP-telefonsamtal.
CommunicateContentStartBörja strömma ljudinnehåll till enheten.
CommunicateContentStopSluta strömma ljudinnehåll.
SocketReceiveStatusFå en statusuppdatering för WebSocket.

Ljudkommandon

Styr högtalarvolym, mikrofonförstärkning, ljudprofiler och uppspelning av text till tal.

AudioPlayStorageSpela upp en ljudfil från enhetens lagringsutrymme.
AudioPlayContentSpela upp strömmat ljudinnehåll.
AudioSetVolumeStäll in högtalarens utgångsvolym.

LED-kommandon

Ställ in LED-färg, ljusstyrka och animationsmönster på märkets indikatorlampa.

DeviceIlluminationSetStäll in LED-färg och belysningsmönster.

Interna kommandon

Interna dispatch-kommandon som används för kontextleverans, kanalhistorik, vokalisering och ljudavkodning.

InternalSendContextSkicka kontextdata till den interna kontexthanteraren.
InternalSendChannelHistorySkicka kanalhistorik till den interna hanteraren.
InternalRequestVocalizationBegär text-till-tal-vokalisering internt.
InternalHandleVocalizationRTPHantera en inkommande vokaliserings-RTP-ström.
InternalDecodeAudioAvkoda en inkommande ljudström.

Mobila kommandon

Kommandon för att koordinera märket med en parad mobilapp – push-meddelanden, synkronisering av appstatus och djuplänkning.

MobileServiceStatusRapportera mobiltjänstens status till enheten. (Mobil → Enhet)
MobileSocketOpenInstruera mobilappen att öppna en WebSocket-anslutning. (Enhet → Mobil)
MobileSocketCloseInstruera mobilappen att stänga en WebSocket-anslutning. (Enhet → Mobil)
MobileSocketStatusRapportera WebSocket-status till mobilappen. (Enhet → Mobil)
MobileReceiveStatusRapportera mottagningsstatus till mobilappen. (Enhet → Mobil)
MobileSocketUpdateSkicka en WebSocket-datauppdatering till mobilappen. (Enhet → Mobil)
MobilePTTStartMeddela mobilappen att PTT-överföringen har startat. (Enhet → Mobil)
MobilePTTStopMeddela mobilappen att PTT-överföringen har avslutats. (Enhet → Mobil)
MobileContextSetStäll in kontextdata i mobilappen. (Enhet → Mobil)
MobileEchoEcho-kommando för att testa mobil anslutning. (Enhet → Mobil)

Redo att bygga?

Gå med i Connections utvecklarcommunity och få tillgång till sandbox-enheter, SDK:er och dedikerad support.

Kontakta oss