Utviklerplattform

Bygg videre på
Tilkoblingsplattform

To kraftige API-er – et RESTful-server-API for enhetsadministrasjon og kommunikasjonsorkestrering, og en lavnivå CBBP-protokoll for direkte merkekontroll.

REST API-referanseCBBP-protokollen
OpenAPI 3.0JSON / RESTBluetooth + Wi-FiWebhook-støtte
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

Fullstendig livssyklusadministrasjon av enheten – klargjøring, konfigurasjon, fastvare, kommunikasjon og analyse – over standard HTTPS.

Utforsk REST API →

CBBP-protokollen

Com Badge Basic Protocol – en JSON-kommandoprotokoll for direkte enhetskontroll via Bluetooth (app), WiFi (serverproxy) eller lokal utsendelse.

Utforsk CBBP →

Webhooks

Abonner på enhetshendelser i sanntid – kommunikasjon, statusendringer, posisjonsoppdateringer – levert som HTTP POST-nyttelaster til endepunktet ditt.

Utforsk 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.

Komme i gang

Autentisering

Connection API bruker Bearer-token-autentisering. Alle forespørsler må inkludere et gyldig JWT-tilgangstoken i Authorization-headeren.

Skaff deg en token

POST legitimasjonen din til autentiseringsendepunktet. Du vil motta et kortlivet access_token og et mer langvarig refresh_token.

Bruk tokenet

Inkluder tokenet i hver forespørsel:

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

Basis-URL og versjonering

Alle API-endepunkter er versjonert under /api/v1/. Basis-URL-en avhenger av implementeringen din.

For skybaserte distribusjoner bruker du det regionale endepunktet som er tilordnet organisasjonen din. For lokale serverdistribusjoner bruker du serverens vertsnavn.

MiljøBasis-URL
Sky (USA)https://beta.connection.app/api/v1
Lokalthttps://<your-server>/api/v1
Innholdstype
Alle forespørsels- og svartekster bruker application/json. Inkluder Content-Type: application/json på forespørsler med en tekst.

Feil og statuskoder

API-et bruker standard HTTP-statuskoder. Feilresponser inkluderer en maskinlesbar kode og en menneskelig lesbar melding.

StatusBetydning
200Suksess
201Opprettet
400Ugyldig forespørsel – ugyldige parametere
401Uautorisert – manglende eller utløpt token
403Forbudt – utilstrekkelige tillatelser
404Ikke funnet
500Intern serverfeil
Feilrespons
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
REST API

Oversikt over REST API

REST API-et for Connection Server gir full programmatisk tilgang til enhetsparken din, kommunikasjonsinfrastrukturen og analysene dine. Det følger RESTful-konvensjoner med JSON-forespørsels-/svarelementer.

API-autentisering
Brukere
Enheter
Kanaler
Kommunikasjon
Lydbro
Samtaler
Innhold
Steder
Push-varsler
Lagring
Masseoperasjoner
Dato og klokkeslett

Autentisering

Tokenbasert autentisering. Innlogging returnerer et token som må sendes som Autorisasjon: Token<token> på alle senere forespørsler.

POST/api/v1/loginAutentiser en bruker og motta et autorisasjonstoken
POST/api/v1/login-deviceAutentiser en enhet med UUID og MAC-adresse
POST/api/v1/logoutUgyldiggjør gjeldende økttoken

Brukere

Opprett og administrer brukerkontoer. GET /users/user-sluttpunktet returnerer den autentiserte brukeren.

GET/api/v1/users/userHent den nåværende påloggede brukerprofilen
POST/api/v1/users/userOpprett en ny brukerkonto
PATCH/api/v1/users/user/{uuid}Oppdater brukerprofil (f.eks. profilbilde)

Enheter

Liste og inspiser enheter, administrer bruker-enhet-tilknytninger, les og skriv innstillinger og status per enhet, håndter fastvare- og lagringsbilder, og motta logger og krasjrapporter.

GET/api/v1/devices/deviceList opp alle enheter
GET/api/v1/devices/device/{uuid}Få detaljert enhetsinformasjon, inkludert fastvare og innstillinger
PUT/api/v1/devices/association/{uuid}Oppdater tilknytningen mellom en bruker og en enhet
DELETE/api/v1/devices/association/{uuid}Fjern bruker-enhetstilknytning og lagrede innstillinger
GET/api/v1/devices/device/{device_uuid}/settingsListe over innstillinger som er lagret for en enhet
POST/api/v1/devices/device/{device_uuid}/settingsLagre enhetsspesifikke innstillinger
GET/api/v1/devices/device/{device_uuid}/statusFå enhetsstatus (tilkobling, batteri, sensorer, lydstatus)
POST/api/v1/devices/device/{device_uuid}/statusLegg ut enhetsstatus fra enheten
GET/api/v1/devices/device/{device_uuid}/contextListe over kontekstverdier lagret for en enhet
POST/api/v1/devices/device/{device_uuid}/ingest-contextMotta GPS + WiFi-kontekst fra enheten
GET/api/v1/devices/firmwareList opp fastvareutgivelser som er kompatible med en gitt maskinvare-/programvareversjon
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchHent et fastvarebilde i biter
GET/api/v1/devices/languageListe over støttede enhetsspråk og stemmer
GET/api/v1/devices/storage_imageLast ned et tilpasset bilde av enhetslagring for en språkinnstilling
POST/api/v1/devices/logMotta en loggfil fra en enhet
POST/api/v1/devices/crashMotta en kjernedump fra en enhet
PATCH/api/v1/devices/crash/{uuid}Oppdater en krasjlogg

CBBP-proxy

Send en hvilken som helst CBBP-kommando til en enhet via serveren. Serveren videresender kommandoen via enhetens WiFi-tilkobling og returnerer enhetens svar. Det utgående make-svaret inneholder også en CBBPMessage som enheten kjører umiddelbart.

POST/api/v1/devices/device/{device_uuid}/cbbpSend en CBBP-kommando til en enhet via serveren
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Hent status og svar på en tidligere sendt CBBP-kommando

Forespørselsteksten er en CBBP-kommandokonvolutt. Det lagrede CBBPCommand-objektet sporer leveringsstatus: UNSET → SENT → RECEIVED eller TIMED_OUT.

Kjør en avstemning mot GET /cbbp/ for å sjekke om enheten mottok og svarte på kommandoen.
Forespørsel — utgående melding
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Svar – CBBP-kommandostatus
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Kanaler

Kanaler er de viktigste kommunikasjonsprimitivene. Typer inkluderer ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService og ChannelRecorder.

GET/api/v1/channels/channelListe over kanaler, eventuelt filtrert etter objekttype
POST/api/v1/channels/channelOpprett en kanal (Kanalgruppe, Kanalkontakt eller Kanaleksterntnummer)
PATCH/api/v1/channels/channel/{uuid}Oppdater en kanalgruppe eller kanalkontakt
DELETE/api/v1/channels/channel/{uuid}Slett en kanal
DELETE/api/v1/channels/{uuid}Slett en kanalgruppe
DELETE/api/v1/channels/by-type/{channelType}Slett alle kanaler av en gitt type (for tiden Kanalkontakt)
GET/api/v1/channels/associationList opp kanaltilknytninger for gjeldende bruker
POST/api/v1/channels/associationBe om en tilknytning til en kanal
PATCH/api/v1/channels/association/{uuid}Godta, avslå eller oppdater tilknytningsinnstillinger
DELETE/api/v1/channels/association/{uuid}Fjern en tilknytning til en kanal
GET/api/v1/channels/historyHent paginert kanaltilgangshistorikk for gjeldende bruker
POST/api/v1/channels/historyOpprett en kanalhistorikkoppføring
GET/api/v1/channels/searchSøk i kanaler etter søkestreng og valgfritt typefilter

Kommunikasjon

Start og administrer aktive kommunikasjonsøkter – utgående anrop, VCP, opptak og strømming av innhold. Svaret på utgående anrop inkluderer en CBBPMessage som enheten reagerer på umiddelbart.

POST/api/v1/communicate/outgoing-makeStart en utgående kanal til en kanalperson, kanalgruppe, kanalkontakt eller kanalkontaktnummer
POST/api/v1/communicate/incoming-acceptanceGodta eller avslå en innkommende forespørsel om kanalinnmelding
POST/api/v1/communicate/closeLukk den gjeldende aktive kommunikasjonskanalen på en enhet
POST/api/v1/communicate/vcp-activateStart Voice Communication Protocol (VCP) på serveren og enheten
POST/api/v1/communicate/vcp-deactivateDeaktiver VCP, gå tilbake til en hvilken som helst forrige kanal
POST/api/v1/communicate/recording-activateAktiver opptaksmodus på serveren og enheten
POST/api/v1/communicate/content-startÅpne en strømmekanal for lydinnhold
POST/api/v1/communicate/request-vocalizationGenerer TTS-lyd for den gitte teksten, eventuelt oversett den

Lydbro

Få tilgang til innspilte brosamtaler, inkludert fullstendige transkripsjoner, deltakerlister og AI-genererte sammendrag. Støtter flere sammendragsmaler (møtenotater, klassenotater, helsevesen osv.) og TTS-lydgenerering for sammendrag.

GET/api/v1/bridge/conversationsList opp alle bridge-samtaler
GET/api/v1/bridge/conversations/{uuid}Få en detaljert samtale inkludert transkripsjon, deltakere og sammendrag
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenerer et AI-sammendrag for en samtale
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenerer lyd for et samtalesammendrag

Samtaler

AI-drevne samtaleøkter ved bruk av ChatGPT, Gemini eller den innebygde søkemotoren. Støtter flere personaer (lege, veileder, mekaniker osv.) og paginert meldingshistorikk.

GET/api/v1/conversations/conversationListe over AI-generatorøkter, filtrerbare etter persona og verktøy
POST/api/v1/conversations/conversationOpprett en ny AI-samtaleøkt
GET/api/v1/conversations/conversation/{uuid}Hent en samtaleøkt med valgfri sammendrags-/fraværsoppdatering
DELETE/api/v1/conversations/conversation/{uuid}Slett en samtaleøkt
GET/api/v1/conversations/conversation/{uuid}/messagesListe opp meldinger i en samtale
POST/api/v1/conversations/conversation/{uuid}/messagesLegg til en brukermelding og motta et AI-svar

Innhold

Bla gjennom og spill av strømmeinnhold på enheter. Innholdet er organisert i et kategoritre; populært innhold kan filtreres etter by, region eller land.

GET/api/v1/content/categoriesFå et tre over innholdskategorier
GET/api/v1/content/contentList opp tilgjengelig innhold i en kategori
GET/api/v1/content/popularList opp populært innhold for en gitt by, region eller land

Steder

Løs geografiske koordinater til et strukturert by-, region- og landsobjekt. Brukes av enheter ved inntak av kontekst.

POST/api/v1/location/determineLøs en breddegrad/lengdegrad til by, region og land

Push-varsler

Registrer en mobilapp for å motta FCM push-varsler. Støtter iOS, Android og nettbaserte mål.

POST/api/v1/push-notifications/pushRegistrer en mobilapp for FCM push-varsler (iOS, Android, nett)

Lagring

Last ned filer lagret på modellobjekter, og kjør fjerning av bildebakgrunn (returnerer base64-kodet resultat).

GET/api/v1/storage/retrieve/{path}Last ned en lagret fil etter bane
POST/api/v1/storage/remove-backgroundFjern bakgrunnen fra et bilde (returnerer base64)

Masseoperasjoner

Utfør flere API-operasjoner i én enkelt HTTP-forespørsel. Send single_transaction=true for å pakke alle operasjoner inn i én atomtransaksjon – en feil på et element ruller tilbake hele batchen.

POST/api/v1/bulkUtfør flere API-operasjoner i én forespørsel, eventuelt som én atomtransaksjon

Dato og klokkeslett

Returnerer gjeldende serverdato og -klokkeslett i GMT+0. Krever ikke autentisering. Brukes av enheter til å synkronisere den interne klokken.

GET/api/v1/current-datetimeReturner gjeldende dato og klokkeslett i GMT+0
CBBP-protokollen

Grunnleggende protokoll for Com Badge

CBBP er en lett JSON-kommandoprotokoll for direkte interaksjon med tilkoblingsmerker. Den gir deg full kontroll over alle maskinvare- og programvarefunksjoner på enheten.

Meldingsformat

Hver CBBP-interaksjon består av en kommandomelding sendt til enheten og en resultatmelding returnert av enheten.

Objektfeltet i både forespørsel og svar inneholder kommandospesifikke data og kan utelates når det ikke er nødvendig.

Fullstendig protokolldokumentasjon er tilgjengelig for registrerte partnere. Kontakt din Connection-representant eller ta kontakt med developer@connectionbadge.com å be om tilgang til den komplette CBBP-kommandoreferansen, inkludert fullstendige forespørsels-/svarskjemaer, feilkoder og integrasjonsveiledninger.
Kommandomelding
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Resultatmelding
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transportere

CBBP-meldinger kan leveres til en badge gjennom tre forskjellige transporter, avhengig av integrasjonsarkitekturen din.

Bluetooth (app)

Send CBBP-kommandoer direkte fra en mobilapp via BLE. Krever at enheten er paret og innenfor rekkevidde.

Mobil SDK

WiFi eller Bluetooth via server

Proxy CBBP gjennom REST API – POST /devices//cbbp. Serveren ruter automatisk til enheten via WiFi eller Bluetooth, avhengig av hvordan skiltet er koblet til. Vanligst for backend-integrasjoner.

REST API

Intern forsendelse

CBBP-forsendelse på enheten eller mellom prosesser. Brukes av badge-fastvaren til å rute kommandoer mellom interne delsystemer.

Kun fastvare

Kraftkommandoer

Kontroller enhetens strømstatus – hvilemodus, vekke, omstart og tilbakestilling til fabrikkinnstillinger.

PowerRebootStart enheten på nytt umiddelbart.
PowerDeepsleepGå inn i dyp søvnmodus (lavt strømforbruk).
FactoryResetSlett all konfigurasjon og tilbakestill til fabrikkinnstillinger.

WiFi-kommandoer

Konfigurer trådløse nettverk, skann etter tilgangspunkter, sjekk tilkoblingsstatus og administrer lagrede påloggingsinformasjoner.

WiFiScanSkann etter tilgjengelige WiFi-tilgangspunkter.
WiFiAPTestTest tilkoblingen til et bestemt WiFi-tilgangspunkt.
WiFiAPJoinKoble til et WiFi-tilgangspunkt med de oppgitte påloggingsinformasjonen.

Bluetooth-kommandoer

Kontroller BLE-annonsering, sammenkobling og kommunikasjon mellom merke.

BTScanBTSkann etter klassiske Bluetooth-enheter.
BTScanBLESkann etter BLE-enheter.
DeviceBLEServiceAvailableMerk BLE-tjenesten som tilgjengelig.
DeviceBLEServiceUnavailableMerk BLE-tjenesten som utilgjengelig.
DeviceBLEActiveSett BLE-radioen til aktiv tilstand.
DeviceBLEIdleSett BLE-radioen i hvilemodus.
DeviceBLEAdvChannelAddLegg til en kanal i BLE-annonseringsnyttelasten.
DeviceBTScanStart en Bluetooth-enhetsskanning.
DeviceBTA2DStartStart Bluetooth A2DP-lydstrømming.
DeviceBTA2DEndAvslutt Bluetooth A2DP-lydstrømming.
DeviceBTNativeAssistStartStart den innebygde Bluetooth-stemmeassistenten.
DeviceBTNativeAssistEndAvslutt den innebygde Bluetooth-stemmeassistenten.

Innstillingskommandoer

Les og skriv enhetskonfigurasjon – visningsnavn, tidssone, språk og funksjonsflagg.

SettingsListGetHent alle innstillinger som en nøkkelverdi-liste.
SettingsListSetSkriv flere innstillingsverdier samtidig.
SettingsGetHent verdien av en enkelt innstilling med nøkkel.
SettingsSetAngi verdien for én innstilling.
SettingsSendSend gjeldende innstillinger til serveren.
SettingsClearFjern spesifikke innstillingsverdier.
SettingsEraseSlett alle lagrede innstillinger.

Fastvarekommandoer

Utløs OTA-fastvareoppdateringer, sjekk oppdateringsstatus og spør om gjeldende fastvareversjon på enheten.

FirmwareCheckSjekk om en fastvareoppdatering er tilgjengelig.
FirmwareUpdateStart en OTA-fastvareoppdatering.
FirmwareValidateValider integriteten til et nedlastet fastvarebilde.

Enhetskommandoer

Enhetens livssyklus, autentisering, konfigurasjon, logging, status og maskinvarekontroll.

NoOpIngen drift / holdes i live.
TestGrunnleggende tilkoblingstest.
DeviceDateTimeHent eller angi dato og klokkeslett for enheten.
DeviceAuthenticateAutentiser enheten med serveren.
DeviceConfigureBruk en konfigurasjonsnyttelast på enheten.
DevicePostConnectionTasksKjør initialiseringsoppgaver etter tilkobling.
DeviceStorageLoadLast inn data fra lagring på enheten.
DeviceLoadCustomAudioLast inn egendefinerte lydfiler på enheten.
DeviceCoredumpSendLast opp en krasjkjernedump til serveren.
DeviceAttachKoble enheten til en serverøkt.
DeviceDetachKoble enheten fra en serverøkt.
DeviceLogSendLast opp enhetslogger til serveren.
DeviceConnectionTestTest servertilkoblingen.
DeviceStatusSendSend enhetsstatus til serveren.
DeviceStatusGetFå gjeldende enhetsstatus.
DeviceInteractionUtløs en hendelse for enhetsinteraksjon.
DeviceSetAPIHostAngi API-serververten.
DeviceTestMicsKjør en selvtest av mikrofonen.
HardwareI2CCommandSend en rå I2C-kommando til en maskinvareperiferienhet.

Kommunikasjonskommandoer

Start samtaler, send meldinger, administrer aktive kommunikasjonsøkter og kontroller opptak.

CommunicateChannelJoinBli med i en kommunikasjonskanal.
CommunicateChannelLeaveLegg igjen en kommunikasjonskanal.
CommunicateChannelChangeBytt til en annen kanal.
CommunicateChannelCloseStenge en kommunikasjonskanal.
CommunicateReceiveIncomingVarsle enheten om innkommende kommunikasjon.
CommunicateRequestOutgoingBe om utgående kommunikasjon.
CommunicateVCPActivateAktiver stemmekommunikasjonsprotokolløkten.
CommunicateVCPDeactivateDeaktiver VCP-økten.
CommunicateRecordingActivateStart opptak av den aktive kommunikasjonen.
CommunicateIncomingAcceptGodta et innkommende anrop.
CommunicateIncomingRejectAvvis et innkommende anrop.
CommunicateHFPCallStartStart en Bluetooth HFP-telefonsamtale.
CommunicateHFPCallEndAvslutt en Bluetooth HFP-telefonsamtale.
CommunicateContentStartBegynn å strømme lydinnhold til enheten.
CommunicateContentStopStopp strømming av lydinnhold.
SocketReceiveStatusMotta en statusoppdatering for WebSocket.

Lydkommandoer

Kontroller høyttalervolum, mikrofonforsterkning, lydprofiler og tekst-til-tale-avspilling.

AudioPlayStorageSpill av en lydfil fra lagringsplassen på enheten.
AudioPlayContentSpill av strømmet lydinnhold.
AudioSetVolumeAngi høyttalerutgangsvolumet.

LED-kommandoer

Angi LED-farge, lysstyrke og animasjonsmønstre på merkeindikatorlampen.

DeviceIlluminationSetAngi LED-fargen og lysmønsteret.

Interne kommandoer

Interne forsendelseskommandoer brukt for kontekstlevering, kanalhistorikk, vokalisering og lyddekoding.

InternalSendContextSend kontekstdata til den interne kontekstbehandleren.
InternalSendChannelHistorySend kanalhistorikk til den interne behandleren.
InternalRequestVocalizationBe om tekst-til-tale-vokalisering internt.
InternalHandleVocalizationRTPHåndter en innkommende vokaliserings-RTP-strøm.
InternalDecodeAudioDekode en innkommende lydstrøm.

Mobilkommandoer

Kommandoer for å koordinere merket med en paret mobilapp – push-varsler, synkronisering av apptilstand og dyplenking.

MobileServiceStatusRapporter status for mobiltjenesten til enheten. (Mobil → Enhet)
MobileSocketOpenInstruer mobilappen til å åpne en WebSocket-tilkobling. (Enhet → Mobil)
MobileSocketCloseInstruer mobilappen til å lukke en WebSocket-tilkobling. (Enhet → Mobil)
MobileSocketStatusRapporter WebSocket-status til mobilappen. (Enhet → Mobil)
MobileReceiveStatusRapporter mottaksstatus til mobilappen. (Enhet → Mobil)
MobileSocketUpdateSend en WebSocket-dataoppdatering til mobilappen. (Enhet → Mobil)
MobilePTTStartVarsle mobilappen om at PTT-overføringen har startet. (Enhet → Mobil)
MobilePTTStopVarsle mobilappen om at PTT-overføringen er avsluttet. (Enhet → Mobil)
MobileContextSetAngi kontekstdata i mobilappen. (Enhet → Mobil)
MobileEchoEkko-kommando for testing av mobiltilkobling. (Enhet → Mobil)

Klar til å bygge?

Bli med i Connection-utviklerfellesskapet og få tilgang til sandkasseenheter, SDK-er og dedikert støtte.

Kontakt oss