Piattaforma per sviluppatori

Costruire sulla
Piattaforma di connessione

Due potenti API: un'API server RESTful per la gestione dei dispositivi e l'orchestrazione delle comunicazioni, e un protocollo CBBP di basso livello per il controllo diretto dei badge.

Riferimento API RESTProtocollo CBBP
OpenAPI 3.0JSON / RESTBluetooth + Wi-FiSupporto Webhook
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

API REST

Gestione completa del ciclo di vita del dispositivo: provisioning, configurazione, firmware, comunicazioni e analisi, tramite HTTPS standard.

Esplora le API REST →

Protocollo CBBP

Protocollo Com Badge Basic — un protocollo di comandi JSON per il controllo diretto dei dispositivi tramite Bluetooth (app), Wi-Fi (server proxy) o dispatch locale.

Scopri CBBP →

Webhooks

Iscriviti per ricevere notifiche in tempo reale sugli eventi del dispositivo, come comunicazioni, modifiche di stato e aggiornamenti di posizione, tramite richieste HTTP POST inviate al tuo endpoint.

Esplora i webhook →

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.

Iniziare

Autenticazione

L'API di connessione utilizza l'autenticazione tramite token Bearer. Tutte le richieste devono includere un token di accesso JWT valido nell'intestazione Authorization.

Ottieni un gettone

Invia le tue credenziali tramite POST all'endpoint di autenticazione. Riceverai un access_token di breve durata e un refresh_token di durata maggiore.

Utilizzare il token

Includi il token in ogni richiesta:

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

URL di base e versioning

Tutti gli endpoint API sono versionati sotto /api/v1/. L'URL di base dipende dalla configurazione del tuo sistema.

Per le implementazioni in cloud, utilizzare l'endpoint regionale assegnato all'organizzazione. Per le implementazioni su server locali, utilizzare il nome host del server.

AmbienteURL di base
Cloud (USA)https://beta.connection.app/api/v1
In locohttps://<your-server>/api/v1
Tipo di contenuto
Tutti i corpi delle richieste e delle risposte utilizzano application/json. Includere Content-Type: application/json nelle richieste con un corpo.

Errori e codici di stato

L'API utilizza i codici di stato HTTP standard. Le risposte di errore includono un codice leggibile dalla macchina e un messaggio leggibile dall'uomo.

StatoSenso
200Successo
201Creato
400Richiesta non valida: parametri non validi
401Non autorizzato: token mancante o scaduto
403Accesso vietato: autorizzazioni insufficienti.
404Non trovato
500Errore interno del server
Risposta di errore
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Panoramica delle API REST

L'API REST di Connection Server fornisce accesso programmatico completo alla flotta di dispositivi, all'infrastruttura di comunicazione e agli strumenti di analisi. Segue le convenzioni RESTful con corpi di richiesta/risposta in formato JSON.

Autenticazione API
Utenti
Dispositivi
Canali
Comunicazione
Ponte audio
Conversazioni
Contenuto
Posizioni
Notifiche push
Magazzinaggio
Operazioni di massa
Data e ora

Autenticazione

Autenticazione basata su token. Il login restituisce un token che deve essere inviato come autorizzazione: Token<token> su tutte le richieste successive.

POST/api/v1/loginAutentica un utente e ricevi un token di autenticazione
POST/api/v1/login-deviceAutenticare un dispositivo tramite UUID e indirizzo MAC
POST/api/v1/logoutInvalidare il token di sessione corrente

Utenti

Crea e gestisci gli account utente. L'endpoint GET /users/user restituisce l'utente attualmente autenticato.

GET/api/v1/users/userRecupera il profilo dell'utente attualmente connesso
POST/api/v1/users/userCrea un nuovo account utente
PATCH/api/v1/users/user/{uuid}Aggiorna il profilo utente (ad esempio, l'immagine del profilo)

Dispositivi

Elenca e ispeziona i dispositivi, gestisci le associazioni utente-dispositivo, leggi e scrivi le impostazioni e lo stato di ciascun dispositivo, gestisci il firmware e le immagini di archiviazione e ricevi i registri e i rapporti di arresto anomalo.

GET/api/v1/devices/deviceElenca tutti i dispositivi
GET/api/v1/devices/device/{uuid}Ottieni informazioni dettagliate sul dispositivo, inclusi firmware e impostazioni.
PUT/api/v1/devices/association/{uuid}Aggiornare l'associazione tra un utente e un dispositivo
DELETE/api/v1/devices/association/{uuid}Rimuovi l'associazione utente-dispositivo e le impostazioni memorizzate
GET/api/v1/devices/device/{device_uuid}/settingsElenca le impostazioni memorizzate per un dispositivo
POST/api/v1/devices/device/{device_uuid}/settingsSalva le impostazioni specifiche del dispositivo
GET/api/v1/devices/device/{device_uuid}/statusOttieni lo stato del dispositivo (connettività, batteria, sensori, stato audio)
POST/api/v1/devices/device/{device_uuid}/statusPubblica lo stato del dispositivo dal dispositivo
GET/api/v1/devices/device/{device_uuid}/contextElenca i valori di contesto memorizzati per un dispositivo
POST/api/v1/devices/device/{device_uuid}/ingest-contextRicevi informazioni GPS + WiFi dal dispositivo
GET/api/v1/devices/firmwareElenca le versioni del firmware compatibili con una determinata versione hardware/software
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchScarica un'immagine del firmware a blocchi
GET/api/v1/devices/languageElenco delle lingue e delle voci supportate dai dispositivi.
GET/api/v1/devices/storage_imageScarica l'immagine di archiviazione del dispositivo personalizzata per una determinata area geografica.
POST/api/v1/devices/logRicevere un file di registro da un dispositivo
POST/api/v1/devices/crashRicevere un dump della memoria da un dispositivo
PATCH/api/v1/devices/crash/{uuid}Aggiornare un record di arresto anomalo

Proxy CBBP

Invia qualsiasi comando CBBP a un dispositivo tramite il server. Il server inoltra il comando tramite la connessione Wi-Fi del dispositivo e restituisce la risposta del dispositivo. La risposta outgoing-make include anche un messaggio CBBPMessage che il dispositivo esegue immediatamente.

POST/api/v1/devices/device/{device_uuid}/cbbpInvia un comando CBBP a un dispositivo tramite il server
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Recupera lo stato e la risposta di un comando CBBP inviato in precedenza

Il corpo della richiesta è un involucro di comando CBBP. L'oggetto CBBPCommand memorizzato tiene traccia dello stato di consegna: NON IMPOSTATO → INVIATO → RICEVUTO o TIMED_OUT.

Eseguire il comando GET /cbbp/ per verificare se il dispositivo ha ricevuto e risposto al comando.
Richiesta — messaggio in uscita
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Risposta — Stato del comando CBBP
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Canali

I canali sono gli elementi fondamentali della comunicazione. I tipi includono ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService e ChannelRecorder.

GET/api/v1/channels/channelElenco dei canali, eventualmente filtrabili per tipo di oggetto
POST/api/v1/channels/channelCrea un canale (Gruppo canali, Contatto canale o Numero esterno canale)
PATCH/api/v1/channels/channel/{uuid}Aggiorna un gruppo di canali o un contatto di canale
DELETE/api/v1/channels/channel/{uuid}Elimina un canale
DELETE/api/v1/channels/{uuid}Eliminare un gruppo di canali
DELETE/api/v1/channels/by-type/{channelType}Elimina tutti i canali di un determinato tipo (attualmente ChannelContact)
GET/api/v1/channels/associationElenca le associazioni dei canali per l'utente corrente
POST/api/v1/channels/associationRichiedi un'associazione con un canale
PATCH/api/v1/channels/association/{uuid}Accetta, rifiuta o aggiorna le impostazioni di associazione
DELETE/api/v1/channels/association/{uuid}Rimuovere l'associazione con un canale
GET/api/v1/channels/historyOttieni la cronologia di accesso al canale paginata per l'utente corrente
POST/api/v1/channels/historyCrea una voce nella cronologia del canale
GET/api/v1/channels/searchCerca canali tramite stringa di ricerca e filtro di tipo opzionale

Comunicazione

Avviare e gestire sessioni di comunicazione attive: chiamate in uscita, VCP, registrazioni e streaming di contenuti. La risposta di chiamata in uscita include un messaggio CBBPMessage sul quale il dispositivo agisce immediatamente.

POST/api/v1/communicate/outgoing-makeAvviare un canale in uscita verso un ChannelPeople, ChannelGroup, ChannelContact o ChannelContactNumber.
POST/api/v1/communicate/incoming-acceptanceAccettare o rifiutare una richiesta di adesione al canale in entrata
POST/api/v1/communicate/closeChiudere il canale di comunicazione attivo corrente su un dispositivo
POST/api/v1/communicate/vcp-activateAvviare il protocollo di comunicazione vocale (VCP) sul server e sul dispositivo.
POST/api/v1/communicate/vcp-deactivateDisattiva VCP, tornando a qualsiasi canale precedente
POST/api/v1/communicate/recording-activateAttivare la modalità di registrazione sul server e sul dispositivo.
POST/api/v1/communicate/content-startApri un canale di streaming per contenuti audio
POST/api/v1/communicate/request-vocalizationGenera audio TTS per il testo fornito, traducendolo facoltativamente.

Ponte audio

Accedi alle registrazioni delle conversazioni di bridge, incluse le trascrizioni complete, gli elenchi dei partecipanti e i riepiloghi generati dall'IA. Supporta diversi modelli di riepilogo (appunti di riunione, appunti di lezione, ambito sanitario, ecc.) e la generazione di sintesi vocale (TTS) per i riepiloghi.

GET/api/v1/bridge/conversationsElenca tutte le conversazioni sul ponte
GET/api/v1/bridge/conversations/{uuid}Ottieni una conversazione dettagliata, comprensiva di trascrizione, partecipanti e riepilogo.
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGenera un riepilogo tramite intelligenza artificiale per una conversazione
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGenera l'audio per un riepilogo della conversazione

Conversazioni

Sessioni di conversazione basate sull'intelligenza artificiale tramite ChatGPT, Gemini o il motore nativo. Supporta diversi profili utente (medico, tutor, meccanico, ecc.) e una cronologia dei messaggi impaginata.

GET/api/v1/conversations/conversationElenco delle sessioni del generatore di IA, filtrabili per persona e strumento
POST/api/v1/conversations/conversationCrea una nuova sessione di conversazione con l'IA
GET/api/v1/conversations/conversation/{uuid}Recupera una sessione di conversazione con riepilogo/aggiornamento di assenza opzionale
DELETE/api/v1/conversations/conversation/{uuid}Eliminare una sessione di conversazione
GET/api/v1/conversations/conversation/{uuid}/messagesElenca i messaggi in una conversazione
POST/api/v1/conversations/conversation/{uuid}/messagesAggiungi un messaggio utente e ricevi una risposta dall'IA

Contenuto

Esplora e riproduci contenuti audio in streaming sui tuoi dispositivi. I contenuti sono organizzati in una struttura ad albero per categorie; i contenuti più popolari possono essere filtrati per città, regione o paese.

GET/api/v1/content/categoriesOttieni una struttura ad albero delle categorie di contenuti
GET/api/v1/content/contentElenca i contenuti disponibili all'interno di una categoria
GET/api/v1/content/popularElenca i contenuti più popolari per una determinata città, regione o paese.

Posizioni

Risolve le coordinate geografiche in un oggetto strutturato che rappresenta città, regione e paese. Utilizzato dai dispositivi per acquisire il contesto.

POST/api/v1/location/determineConvertire una latitudine/longitudine in città, regione e paese.

Notifiche push

Registra un'app mobile per ricevere le notifiche push di FCM. Supporta dispositivi iOS, Android e web.

POST/api/v1/push-notifications/pushRegistra un'app mobile per ricevere notifiche push da FCM (iOS, Android, web)

Magazzinaggio

Scarica i file memorizzati sugli oggetti del modello ed esegui la rimozione dello sfondo dell'immagine (restituisce un risultato codificato in base64).

GET/api/v1/storage/retrieve/{path}Scarica un file salvato tramite percorso
POST/api/v1/storage/remove-backgroundRimuove lo sfondo da un'immagine (restituisce base64)

Operazioni di massa

Esegui più operazioni API in una singola richiesta HTTP. Imposta single_transaction=true per racchiudere tutte le operazioni in un'unica transazione atomica: un errore su qualsiasi elemento annullerà l'intero batch.

POST/api/v1/bulkEseguire più operazioni API in una singola richiesta, facoltativamente come un'unica transazione atomica.

Data e ora

Restituisce la data e l'ora correnti del server in formato GMT+0. Non richiede autenticazione. Utilizzato dai dispositivi per sincronizzare il proprio orologio interno.

GET/api/v1/current-datetimeRestituisci la data e l'ora correnti nel formato GMT+0
Protocollo CBBP

Protocollo base Com Badge

CBBP è un protocollo di comandi JSON leggero per l'interazione diretta con i badge di connessione. Offre il pieno controllo su ogni funzione hardware e software del dispositivo.

Formato di comunicazione

Ogni interazione CBBP consiste in un messaggio di comando inviato al dispositivo e in un messaggio di risultato restituito dal dispositivo.

Il campo oggetto, sia nella richiesta che nella risposta, contiene dati specifici del comando e può essere omesso quando non necessario.

La documentazione completa del protocollo è disponibile per i partner registrati. Contatta il tuo rappresentante commerciale Connection o rivolgiti a developer@connectionbadge.com per richiedere l'accesso al manuale di riferimento completo dei comandi CBBP, inclusi gli schemi completi di richiesta/risposta, i codici di errore e le guide all'integrazione.
Divisione di Comando
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Gestione dei risultati
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Trasporto

I messaggi CBBP possono essere recapitati a un badge tramite tre diversi protocolli di trasporto, a seconda dell'architettura di integrazione.

Bluetooth (App)

Invia comandi CBBP direttamente da un'app mobile tramite BLE. Richiede che il dispositivo sia associato e si trovi nel raggio d'azione.

SDK per dispositivi mobili

Wi-Fi o Bluetooth tramite server

Eseguire il proxy CBBP tramite l'API REST — POST /devices//cbbp. Il server instrada automaticamente la richiesta al dispositivo tramite Wi-Fi o Bluetooth a seconda di come è connesso il badge. Questa soluzione è la più comune per le integrazioni backend.

API REST

Dispaccio interno

Inoltro CBBP a livello di dispositivo o tra processi. Utilizzato dal firmware del badge per instradare i comandi tra i sottosistemi interni.

Solo firmware

Comandi di alimentazione

Controllo dello stato di alimentazione del dispositivo: sospensione, riattivazione, riavvio e ripristino delle impostazioni di fabbrica.

PowerRebootRiavviare immediatamente il dispositivo.
PowerDeepsleepAttiva la modalità di sospensione profonda (a basso consumo energetico).
FactoryResetCancella tutta la configurazione e ripristina le impostazioni di fabbrica.

Comandi WiFi

Configura le reti wireless, esegui la scansione degli access point, verifica lo stato della connessione e gestisci le credenziali salvate.

WiFiScanCerca i punti di accesso Wi-Fi disponibili.
WiFiAPTestVerifica la connettività a uno specifico punto di accesso Wi-Fi.
WiFiAPJoinConnettiti a un punto di accesso Wi-Fi utilizzando le credenziali fornite.

Comandi Bluetooth

Gestisci la pubblicità BLE, l'accoppiamento e la comunicazione tra badge.

BTScanBTCerca dispositivi Bluetooth classici.
BTScanBLECerca dispositivi BLE.
DeviceBLEServiceAvailableContrassegna il servizio BLE come disponibile.
DeviceBLEServiceUnavailableContrassegna il servizio BLE come non disponibile.
DeviceBLEActiveImpostare il modulo radio BLE sullo stato attivo.
DeviceBLEIdleImpostare il modulo radio BLE in stato di inattività.
DeviceBLEAdvChannelAddAggiungi un canale al payload pubblicitario BLE.
DeviceBTScanAvviare una scansione dei dispositivi Bluetooth.
DeviceBTA2DStartAvvia lo streaming audio Bluetooth A2DP.
DeviceBTA2DEndTermina lo streaming audio Bluetooth A2DP.
DeviceBTNativeAssistStartAvvia l'assistente vocale Bluetooth nativo.
DeviceBTNativeAssistEndTermina l'assistente vocale Bluetooth nativo.

Comandi delle impostazioni

Lettura e scrittura della configurazione del dispositivo: nome visualizzato, fuso orario, lingua e flag delle funzionalità.

SettingsListGetRecupera tutte le impostazioni come elenco chiave-valore.
SettingsListSetScrivi più valori di impostazione contemporaneamente.
SettingsGetOttieni il valore di una singola impostazione tramite la chiave.
SettingsSetImposta il valore di una singola impostazione.
SettingsSendInvia le impostazioni correnti al server.
SettingsClearValori di impostazione specifici e chiarisci.
SettingsEraseCancella tutte le impostazioni memorizzate.

Comandi del firmware

Avvia gli aggiornamenti firmware OTA, verifica lo stato degli aggiornamenti e interroga la versione firmware corrente sul dispositivo.

FirmwareCheckVerifica se è disponibile un aggiornamento del firmware.
FirmwareUpdateAvviare un aggiornamento firmware OTA.
FirmwareValidateVerificare l'integrità di un'immagine firmware scaricata.

Comandi del dispositivo

Ciclo di vita del dispositivo, autenticazione, configurazione, registrazione, stato e controllo hardware.

NoOpNessuna operazione / mantenimento in vita.
TestTest di connettività di base.
DeviceDateTimeOttenere o impostare la data e l'ora del dispositivo.
DeviceAuthenticateAutenticare il dispositivo con il server.
DeviceConfigureApplicare un payload di configurazione al dispositivo.
DevicePostConnectionTasksEseguire le attività di inizializzazione successive alla connessione.
DeviceStorageLoadCarica i dati dalla memoria interna del dispositivo.
DeviceLoadCustomAudioCarica file audio personalizzati sul dispositivo.
DeviceCoredumpSendCarica il file di dump dell'arresto anomalo sul server.
DeviceAttachCollega il dispositivo a una sessione server.
DeviceDetachScollega il dispositivo dalla sessione del server.
DeviceLogSendCarica i log del dispositivo sul server.
DeviceConnectionTestVerifica la connettività del server.
DeviceStatusSendInvia lo stato del dispositivo al server.
DeviceStatusGetOttieni lo stato attuale del dispositivo.
DeviceInteractionAttiva un evento di interazione con il dispositivo.
DeviceSetAPIHostImposta l'host del server API.
DeviceTestMicsEsegui un test di autodiagnosi del microfono.
HardwareI2CCommandInvia un comando I2C grezzo a una periferica hardware.

Comandi di comunicazione

Avviare chiamate, inviare messaggi, gestire sessioni di comunicazione attive e controllare le registrazioni.

CommunicateChannelJoinUnisciti a un canale di comunicazione.
CommunicateChannelLeaveLascia un canale di comunicazione.
CommunicateChannelChangePassa a un altro canale.
CommunicateChannelCloseChiudere un canale di comunicazione.
CommunicateReceiveIncomingNotifica al dispositivo l'arrivo di una comunicazione.
CommunicateRequestOutgoingRichiedi una comunicazione in uscita.
CommunicateVCPActivateAttiva la sessione del protocollo di comunicazione vocale.
CommunicateVCPDeactivateDisattiva la sessione VCP.
CommunicateRecordingActivateAvviare la registrazione della comunicazione attiva.
CommunicateIncomingAcceptRispondere a una chiamata in arrivo.
CommunicateIncomingRejectRifiutare una chiamata in arrivo.
CommunicateHFPCallStartAvvia una chiamata telefonica Bluetooth HFP.
CommunicateHFPCallEndTerminare una chiamata telefonica Bluetooth HFP.
CommunicateContentStartAvvia lo streaming del contenuto audio sul dispositivo.
CommunicateContentStopInterrompi lo streaming di contenuti audio.
SocketReceiveStatusRicevi un aggiornamento sullo stato del WebSocket.

Comandi audio

Consente di controllare il volume degli altoparlanti, il guadagno del microfono, i profili audio e la riproduzione della sintesi vocale.

AudioPlayStorageRiproduci un file audio dalla memoria interna del dispositivo.
AudioPlayContentRiproduci contenuti audio in streaming.
AudioSetVolumeRegola il volume di uscita degli altoparlanti.

Comandi LED

Imposta il colore, la luminosità e le animazioni del LED sull'indicatore luminoso del badge.

DeviceIlluminationSetImposta il colore del LED e la modalità di illuminazione.

Comandi interni

Comandi di dispatch interni utilizzati per la trasmissione del contesto, la cronologia del canale, la vocalizzazione e la decodifica audio.

InternalSendContextInvia i dati di contesto al gestore di contesto interno.
InternalSendChannelHistoryInvia la cronologia del canale al gestore interno.
InternalRequestVocalizationRichiedi la vocalizzazione interna del testo in sintesi vocale.
InternalHandleVocalizationRTPGestire un flusso RTP di vocalizzazione in ingresso.
InternalDecodeAudioDecodifica un flusso audio in ingresso.

Comandi mobili

Comandi per coordinare il badge con un'app mobile associata: notifiche push, sincronizzazione dello stato dell'app e deep linking.

MobileServiceStatusSegnala lo stato del servizio mobile al dispositivo. (Cellulare → Dispositivo)
MobileSocketOpenIndica all'app mobile di aprire una connessione WebSocket. (Dispositivo → Mobile)
MobileSocketCloseIndica all'app mobile di chiudere una connessione WebSocket. (Dispositivo → Mobile)
MobileSocketStatusSegnala lo stato del WebSocket all'app mobile. (Dispositivo → Mobile)
MobileReceiveStatusSegnala lo stato di ricezione all'app mobile. (Dispositivo → Mobile)
MobileSocketUpdateInvia un aggiornamento dati WebSocket all'app mobile. (Dispositivo → Mobile)
MobilePTTStartNotifica all'app mobile che la trasmissione PTT è iniziata. (Dispositivo → Mobile)
MobilePTTStopNotifica all'app mobile che la trasmissione PTT è terminata. (Dispositivo → Mobile)
MobileContextSetImposta i dati di contesto sull'app mobile. (Dispositivo → Mobile)
MobileEchoComando Echo per testare la connettività mobile. (Dispositivo → Mobile)

Pronti a costruire?

Unisciti alla community di sviluppatori di Connection e accedi a dispositivi sandbox, SDK e supporto dedicato.

Contattaci