Plateforme développeur

Construisez sur la
Plateforme Connection

Deux APIs puissantes — une API serveur RESTful pour la gestion des appareils et l'orchestration des communications, et un protocole CBBP bas niveau pour le contrôle direct du badge.

Référence API RESTProtocole CBBP
OpenAPI 3.0JSON / RESTBluetooth + WiFiSupport 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

Gestion complète du cycle de vie des appareils — provisionnement, configuration, firmware, communications et analytique — via HTTPS standard.

Explorer l'API REST →

Protocole CBBP

Com Badge Basic Protocol — un protocole de commande JSON pour le contrôle direct des appareils via Bluetooth (application), WiFi (proxy serveur) ou dispatch local.

Explorer CBBP →

Webhooks

Abonnez-vous aux événements d'appareils en temps réel — communications, changements de statut, mises à jour de localisation — livrés comme payloads HTTP POST à votre endpoint.

Explorer les 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.

Démarrage

Authentification

L'API Connection utilise l'authentification par token Bearer. Toutes les requêtes doivent inclure un token d'accès JWT valide dans l'en-tête Authorization.

Obtenir un token

Envoyez vos identifiants en POST à l'endpoint d'authentification. Vous recevrez un access_token de courte durée et un refresh_token de longue durée.

Utiliser le token

Incluez le token dans chaque requête :

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Requête
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Réponse 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

URL de base et versionnage

Tous les endpoints API sont versionnés sous /api/v1/. L'URL de base dépend de votre déploiement.

Pour les déploiements hébergés dans le cloud, utilisez l'endpoint régional assigné à votre organisation. Pour les déploiements Serveur sur site, utilisez le nom d'hôte de votre serveur.

EnvironnementURL de base
Cloud (US)https://beta.connection.app/api/v1
Sur sitehttps://<your-server>/api/v1
Content-Type
Tous les corps de requête et réponse utilisent application/json. Incluez Content-Type: application/json sur les requêtes avec un corps.

Erreurs et codes de statut

L'API utilise des codes de statut HTTP standard. Les réponses d'erreur incluent un code lisible par machine et un message lisible par l'humain.

StatutSignification
200Succès
201Créé
400Mauvaise requête — paramètres invalides
401Non autorisé — token manquant ou expiré
403Interdit — permissions insuffisantes
404Non trouvé
500Erreur interne du serveur
Réponse d'erreur
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Vue d'ensemble de l'API REST

L'API REST Serveur Connection fournit un accès programmatique complet à votre flotte d'appareils, infrastructure de communications et analytique. Elle suit les conventions RESTful avec des corps de requête/réponse JSON.

Authentification API
Utilisateurs
Appareils
Canaux
Communication
Pont audio
Conversations
Contenu
Localisations
Notifications push
Stockage
Opérations en masse
Date et heure

Authentification

Authentification par token. La connexion retourne un token qui doit être envoyé comme Authorization: Token <token> sur toutes les requêtes suivantes.

POST/api/v1/loginAuthentifiez un utilisateur et recevez un token d'authentification
POST/api/v1/login-deviceAuthentifiez un appareil par UUID et adresse MAC
POST/api/v1/logoutInvalidez le token de session actuel

Utilisateurs

Créez et gérez des comptes utilisateurs. L'endpoint GET /users/user retourne l'utilisateur actuellement authentifié.

GET/api/v1/users/userRécupérez le profil de l'utilisateur actuellement connecté
POST/api/v1/users/userCréez un nouveau compte utilisateur
PATCH/api/v1/users/user/{uuid}Mettez à jour le profil utilisateur (ex. : image de profil)

Appareils

Listez et inspectez les appareils, gérez les associations utilisateur-appareil, lisez et écrivez les paramètres et statuts par appareil, gérez les images firmware et stockage, et recevez les journaux et rapports de crash.

GET/api/v1/devices/deviceListez tous les appareils
GET/api/v1/devices/device/{uuid}Obtenez les informations détaillées de l'appareil incluant firmware et paramètres
PUT/api/v1/devices/association/{uuid}Mettez à jour l'association entre un utilisateur et un appareil
DELETE/api/v1/devices/association/{uuid}Supprimez l'association utilisateur-appareil et les paramètres stockés
GET/api/v1/devices/device/{device_uuid}/settingsListez les paramètres stockés pour un appareil
POST/api/v1/devices/device/{device_uuid}/settingsSauvegardez les paramètres spécifiques à l'appareil
GET/api/v1/devices/device/{device_uuid}/statusObtenez le statut de l'appareil (connectivité, batterie, capteurs, état audio)
POST/api/v1/devices/device/{device_uuid}/statusPubliez le statut de l'appareil depuis l'appareil
GET/api/v1/devices/device/{device_uuid}/contextListez les valeurs de contexte stockées pour un appareil
POST/api/v1/devices/device/{device_uuid}/ingest-contextRecevez le contexte GPS + WiFi depuis l'appareil
GET/api/v1/devices/firmwareListez les versions firmware compatibles avec une version hardware/logiciel donnée
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchRécupérez une image firmware par morceaux
GET/api/v1/devices/languageListez les langues et voix d'appareil supportées
GET/api/v1/devices/storage_imageTéléchargez l'image de stockage d'appareil personnalisée pour une locale
POST/api/v1/devices/logRecevez un fichier journal depuis un appareil
POST/api/v1/devices/crashRecevez un dump de mémoire depuis un appareil
PATCH/api/v1/devices/crash/{uuid}Mettez à jour un enregistrement de crash

Proxy CBBP

Envoyez n'importe quelle commande CBBP à un appareil via le serveur. Le serveur relaie la commande via la connexion WiFi de l'appareil et retourne la réponse de l'appareil. La réponse outgoing-make intègre également un CBBPMessage que l'appareil exécute immédiatement.

POST/api/v1/devices/device/{device_uuid}/cbbpEnvoyez une commande CBBP à un appareil via le serveur
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Récupérez le statut et la réponse d'une commande CBBP précédemment envoyée

Le corps de la requête est une enveloppe de commande CBBP. L'objet CBBPCommand stocké suit le statut de livraison : UNSET → SENT → RECEIVED ou TIMED_OUT.

Interrogez GET /cbbp/ pour vérifier si l'appareil a reçu et répondu à la commande.
Requête — outgoingMessage
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Réponse — statut CBBPCommand
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Canaux

Les canaux sont les primitives de communication principales. Les types incluent ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService et ChannelRecorder.

GET/api/v1/channels/channelListez les canaux, optionnellement filtrés par object_type
POST/api/v1/channels/channelCréez un canal (ChannelGroup, ChannelContact ou ChannelExternalNumber)
PATCH/api/v1/channels/channel/{uuid}Mettez à jour un ChannelGroup ou ChannelContact
DELETE/api/v1/channels/channel/{uuid}Supprimez un canal
DELETE/api/v1/channels/{uuid}Supprimez un ChannelGroup
DELETE/api/v1/channels/by-type/{channelType}Supprimez tous les canaux d'un type donné (actuellement ChannelContact)
GET/api/v1/channels/associationListez les associations de canaux pour l'utilisateur actuel
POST/api/v1/channels/associationDemandez une association avec un canal
PATCH/api/v1/channels/association/{uuid}Acceptez, refusez ou mettez à jour les paramètres d'association
DELETE/api/v1/channels/association/{uuid}Supprimez une association avec un canal
GET/api/v1/channels/historyObtenez l'historique d'accès au canal paginé pour l'utilisateur actuel
POST/api/v1/channels/historyCréez une entrée d'historique de canal
GET/api/v1/channels/searchRecherchez des canaux par chaîne de requête et filtre de type optionnel

Communication

Initiez et gérez les sessions de communication actives — appels sortants, VCP, enregistrement et streaming de contenu. La réponse outgoing-make inclut un CBBPMessage sur lequel l'appareil agit immédiatement.

POST/api/v1/communicate/outgoing-makeInitiez un canal sortant vers un ChannelPeople, ChannelGroup, ChannelContact ou ChannelContactNumber
POST/api/v1/communicate/incoming-acceptanceAcceptez ou refusez une demande d'entrée de canal entrante
POST/api/v1/communicate/closeFermez le canal de communication actif actuel sur un appareil
POST/api/v1/communicate/vcp-activateInitiez le protocole de communication vocale (VCP) sur le serveur et l'appareil
POST/api/v1/communicate/vcp-deactivateDésactivez VCP, retournant à tout canal précédent
POST/api/v1/communicate/recording-activateActivez le mode d'enregistrement sur le serveur et l'appareil
POST/api/v1/communicate/content-startOuvrez un canal de streaming vers du contenu audio
POST/api/v1/communicate/request-vocalizationGénérez de l'audio TTS pour le texte donné, en le traduisant optionnellement

Pont audio

Accédez aux conversations de pont enregistrées incluant les transcriptions complètes, listes de participants et résumés générés par IA. Supporte plusieurs modèles de résumés (notes de réunion, notes de cours, santé, etc.) et la génération audio TTS pour les résumés.

GET/api/v1/bridge/conversationsListez toutes les conversations de pont
GET/api/v1/bridge/conversations/{uuid}Obtenez une conversation détaillée incluant transcription, participants et résumé
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGénérez un résumé IA pour une conversation
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGénérez de l'audio pour un résumé de conversation

Conversations

Sessions de conversation propulsées par IA utilisant ChatGPT, Gemini ou le moteur natif. Supporte plusieurs personas (Médecin, Tuteur, Mécanicien, etc.) et l'historique de messages paginé.

GET/api/v1/conversations/conversationListez les sessions de générateur IA, filtrables par persona et outil
POST/api/v1/conversations/conversationCréez une nouvelle session de conversation IA
GET/api/v1/conversations/conversation/{uuid}Récupérez une session de conversation avec mise à jour résumé/absent optionnelle
DELETE/api/v1/conversations/conversation/{uuid}Supprimez une session de conversation
GET/api/v1/conversations/conversation/{uuid}/messagesListez les messages dans une conversation
POST/api/v1/conversations/conversation/{uuid}/messagesAjoutez un message utilisateur et recevez une réponse IA

Contenu

Parcourez et lisez du contenu audio en streaming sur les appareils. Le contenu est organisé en arborescence de catégories ; le contenu populaire peut être filtré par ville, région ou pays.

GET/api/v1/content/categoriesObtenez un arbre de catégories de contenu
GET/api/v1/content/contentListez le contenu disponible dans une catégorie
GET/api/v1/content/popularListez le contenu populaire pour une ville, région ou pays donnés

Localisations

Résolvez les coordonnées géographiques en un objet ville, région et pays structuré. Utilisé par les appareils lors de l'ingestion de contexte.

POST/api/v1/location/determineRésolvez une latitude/longitude en ville, région et pays

Notifications push

Enregistrez une application mobile pour recevoir des notifications push FCM. Supporte les cibles iOS, Android et web.

POST/api/v1/push-notifications/pushEnregistrez une application mobile pour les notifications push FCM (iOS, Android, web)

Stockage

Téléchargez les fichiers stockés sur les objets de modèle, et exécutez la suppression du fond d'image (retourne un résultat encodé en base64).

GET/api/v1/storage/retrieve/{path}Téléchargez un fichier stocké par chemin
POST/api/v1/storage/remove-backgroundSupprimez le fond d'une image (retourne en base64)

Opérations en masse

Exécutez plusieurs opérations API dans une seule requête HTTP. Passez single_transaction=true pour envelopper toutes les opérations dans une seule transaction atomique — un échec sur n'importe quel élément annule tout le lot.

POST/api/v1/bulkExécutez plusieurs opérations API dans une seule requête, optionnellement comme une seule transaction atomique

Date et heure

Retourne la date et l'heure actuelles du serveur en GMT+0. Ne nécessite pas d'authentification. Utilisé par les appareils pour synchroniser leur horloge interne.

GET/api/v1/current-datetimeRetournez la date et l'heure actuelles en GMT+0
Protocole CBBP

Com Badge Basic Protocol

CBBP est un protocole de commande JSON léger pour l'interaction directe avec les badges Connection. Il vous donne un contrôle total sur chaque fonction hardware et logicielle de l'appareil.

Format des messages

Chaque interaction CBBP consiste en un message de commande envoyé à l'appareil et un message de résultat retourné par l'appareil.

Le champ objet dans la requête et la réponse porte les données spécifiques à la commande et peut être omis quand ce n'est pas nécessaire.

La documentation complète du protocole est disponible pour les partenaires enregistrés. Contactez votre représentant commercial Connection ou écrivez à developer@connectionbadge.com pour demander l'accès à la référence complète des commandes CBBP, incluant les schémas complets requête/réponse, codes d'erreur et guides d'intégration.
Message de commande
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Message de résultat
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transport

Les messages CBBP peuvent être délivrés à un badge via trois transports différents selon votre architecture d'intégration.

Bluetooth (Application)

Envoyez des commandes CBBP directement depuis une application mobile via BLE. Nécessite que l'appareil soit couplé et à portée.

SDK Mobile

WiFi ou Bluetooth via Serveur

Proxifiez CBBP via l'API REST — POST /devices//cbbp. Le serveur route automatiquement vers l'appareil via WiFi ou Bluetooth selon la façon dont le badge est connecté. Le plus courant pour les intégrations backend.

API REST

Dispatch interne

Dispatch CBBP sur appareil ou inter-processus. Utilisé par le firmware du badge pour router les commandes entre les sous-systèmes internes.

Firmware uniquement

Commandes d'alimentation

Contrôlez l'état d'alimentation de l'appareil — veille, réveil, redémarrage et réinitialisation d'usine.

PowerRebootRedémarrez l'appareil immédiatement.
PowerDeepsleepEntrez en mode veille profonde (basse consommation).
FactoryResetEffacez toute la configuration et réinitialisez aux paramètres d'usine.

Commandes WiFi

Configurez les réseaux sans fil, scannez les AP, vérifiez le statut de connexion et gérez les identifiants sauvegardés.

WiFiScanScannez les points d'accès WiFi disponibles.
WiFiAPTestTestez la connectivité vers un point d'accès WiFi spécifique.
WiFiAPJoinRejoignez un point d'accès WiFi avec les identifiants fournis.

Commandes Bluetooth

Contrôlez la publicité BLE, le couplage et la communication badge-à-badge.

BTScanBTScannez les appareils Bluetooth classiques.
BTScanBLEScannez les appareils BLE.
DeviceBLEServiceAvailableMarquez le service BLE comme disponible.
DeviceBLEServiceUnavailableMarquez le service BLE comme indisponible.
DeviceBLEActiveMettez la radio BLE en état actif.
DeviceBLEIdleMettez la radio BLE en état idle.
DeviceBLEAdvChannelAddAjoutez un canal au payload de publicité BLE.
DeviceBTScanInitiez un scan d'appareils Bluetooth.
DeviceBTA2DStartDémarrez le streaming audio Bluetooth A2DP.
DeviceBTA2DEndTerminez le streaming audio Bluetooth A2DP.
DeviceBTNativeAssistStartDémarrez l'assistant vocal Bluetooth natif.
DeviceBTNativeAssistEndTerminez l'assistant vocal Bluetooth natif.

Commandes de paramètres

Lisez et écrivez la configuration de l'appareil — nom d'affichage, fuseau horaire, langue et indicateurs de fonctionnalités.

SettingsListGetRécupérez tous les paramètres sous forme de liste clé-valeur.
SettingsListSetÉcrivez plusieurs valeurs de paramètres à la fois.
SettingsGetObtenez la valeur d'un seul paramètre par clé.
SettingsSetDéfinissez la valeur d'un seul paramètre.
SettingsSendPubliez les paramètres actuels vers le serveur.
SettingsClearEffacez des valeurs de paramètres spécifiques.
SettingsEraseEffacez tous les paramètres stockés.

Commandes firmware

Déclenchez les mises à jour firmware OTA, vérifiez le statut des mises à jour et interrogez la version firmware actuelle sur l'appareil.

FirmwareCheckVérifiez si une mise à jour firmware est disponible.
FirmwareUpdateDémarrez une mise à jour firmware OTA.
FirmwareValidateValidez l'intégrité d'une image firmware téléchargée.

Commandes appareil

Cycle de vie de l'appareil, authentification, configuration, journalisation, statut et contrôle hardware.

NoOpNo-operation / keep-alive.
TestTest de connectivité de base.
DeviceDateTimeObtenez ou définissez la date et l'heure de l'appareil.
DeviceAuthenticateAuthentifiez l'appareil avec le serveur.
DeviceConfigureAppliquez un payload de configuration à l'appareil.
DevicePostConnectionTasksExécutez les tâches d'initialisation post-connexion.
DeviceStorageLoadChargez les données depuis le stockage de l'appareil.
DeviceLoadCustomAudioChargez des fichiers audio personnalisés sur l'appareil.
DeviceCoredumpSendUploadez un dump de mémoire de crash vers le serveur.
DeviceAttachAttachez l'appareil à une session serveur.
DeviceDetachDétachez l'appareil d'une session serveur.
DeviceLogSendUploadez les journaux de l'appareil vers le serveur.
DeviceConnectionTestTestez la connectivité serveur.
DeviceStatusSendPubliez le statut de l'appareil vers le serveur.
DeviceStatusGetObtenez le statut actuel de l'appareil.
DeviceInteractionDéclenchez un événement d'interaction de l'appareil.
DeviceSetAPIHostDéfinissez l'hôte du serveur API.
DeviceTestMicsExécutez un auto-test du microphone.
HardwareI2CCommandEnvoyez une commande I2C brute à un périphérique hardware.

Commandes de communication

Initiez des appels, envoyez des messages, gérez les sessions de communication actives et contrôlez l'enregistrement.

CommunicateChannelJoinRejoignez un canal de communication.
CommunicateChannelLeaveQuittez un canal de communication.
CommunicateChannelChangePassez à un canal différent.
CommunicateChannelCloseFermez un canal de communication.
CommunicateReceiveIncomingNotifiez l'appareil d'une communication entrante.
CommunicateRequestOutgoingDemandez une communication sortante.
CommunicateVCPActivateActivez la session de protocole de communication vocale.
CommunicateVCPDeactivateDésactivez la session VCP.
CommunicateRecordingActivateDémarrez l'enregistrement de la communication active.
CommunicateIncomingAcceptAcceptez un appel entrant.
CommunicateIncomingRejectRefusez un appel entrant.
CommunicateHFPCallStartDémarrez un appel téléphonique Bluetooth HFP.
CommunicateHFPCallEndTerminez un appel téléphonique Bluetooth HFP.
CommunicateContentStartCommencez le streaming de contenu audio vers l'appareil.
CommunicateContentStopArrêtez le streaming de contenu audio.
SocketReceiveStatusRecevez une mise à jour de statut WebSocket.

Commandes audio

Contrôlez le volume du haut-parleur, le gain du microphone, les profils audio et la lecture TTS.

AudioPlayStorageLisez un fichier audio depuis le stockage de l'appareil.
AudioPlayContentLisez du contenu audio en streaming.
AudioSetVolumeDéfinissez le volume de sortie du haut-parleur.

Commandes LED

Définissez la couleur, la luminosité et les patterns d'animation de la LED indicatrice du badge.

DeviceIlluminationSetDéfinissez la couleur et le pattern d'illumination de la LED.

Commandes internes

Commandes de dispatch interne utilisées pour la livraison de contexte, l'historique de canal, la vocalisation et le décodage audio.

InternalSendContextEnvoyez des données de contexte au gestionnaire de contexte interne.
InternalSendChannelHistoryEnvoyez l'historique de canal au gestionnaire interne.
InternalRequestVocalizationDemandez la vocalisation TTS en interne.
InternalHandleVocalizationRTPGérez un flux RTP de vocalisation entrant.
InternalDecodeAudioDécodez un flux audio entrant.

Commandes mobiles

Commandes pour coordonner le badge avec une application mobile couplée — notifications push, synchronisation d'état de l'application et deep linking.

MobileServiceStatusRapportez le statut du service mobile à l'appareil. (Mobile → Appareil)
MobileSocketOpenDemandez à l'application mobile d'ouvrir une connexion WebSocket. (Appareil → Mobile)
MobileSocketCloseDemandez à l'application mobile de fermer une connexion WebSocket. (Appareil → Mobile)
MobileSocketStatusRapportez le statut WebSocket à l'application mobile. (Appareil → Mobile)
MobileReceiveStatusRapportez le statut de réception à l'application mobile. (Appareil → Mobile)
MobileSocketUpdateEnvoyez une mise à jour de données WebSocket à l'application mobile. (Appareil → Mobile)
MobilePTTStartNotifiez l'application mobile que la transmission PTT a démarré. (Appareil → Mobile)
MobilePTTStopNotifiez l'application mobile que la transmission PTT s'est terminée. (Appareil → Mobile)
MobileContextSetDéfinissez des données de contexte sur l'application mobile. (Appareil → Mobile)
MobileEchoCommande écho pour tester la connectivité mobile. (Appareil → Mobile)

Prêt à construire ?

Rejoignez la communauté développeur Connection et accédez aux appareils sandbox, SDKs et support dédié.

Contactez-nous