Authentifizierung
Die Connection API verwendet Bearer-Token-Authentifizierung. Alle Anfragen müssen ein gültiges JWT-Zugriffstoken im Authorization-Header enthalten.
Hol dir ein Token
Senden Sie Ihre Anmeldeinformationen per POST an den Authentifizierungsendpunkt. Sie erhalten ein kurzlebiges Zugriffstoken und ein länger gültiges Aktualisierungstoken.
Verwenden Sie das Token.
Fügen Sie das Token in jede Anfrage ein:
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"access_token": "eyJhbG...",
"refresh_token": "dGhpcw...",
"expires_in": 3600,
"token_type": "Bearer"
}Basis-URL & Versionierung
Alle API-Endpunkte sind unter /api/v1/ versioniert. Die Basis-URL hängt von Ihrer Bereitstellung ab.
Bei Cloud-basierten Bereitstellungen verwenden Sie den Ihrer Organisation zugewiesenen regionalen Endpunkt. Bei lokalen Serverbereitstellungen verwenden Sie den Hostnamen Ihres Servers.
| Umfeld | Basis-URL |
|---|---|
| Cloud (USA) | https://beta.connection.app/api/v1 |
| Vor Ort | https://<your-server>/api/v1 |
Alle Anfrage- und Antworttexte verwenden application/json. Fügen Sie Content-Type: application/json zu Anfragen mit einem Textkörper hinzu.
Fehler & Statuscodes
Die API verwendet standardmäßige HTTP-Statuscodes. Fehlermeldungen enthalten einen maschinenlesbaren Code und eine für Menschen lesbare Meldung.
| Status | Bedeutung |
|---|---|
| 200 | Erfolg |
| 201 | Erstellt |
| 400 | Fehlerhafte Anfrage – ungültige Parameter |
| 401 | Nicht autorisiert – fehlendes oder abgelaufenes Token |
| 403 | Verboten – unzureichende Berechtigungen |
| 404 | Nicht gefunden |
| 500 | interner Serverfehler |
{
"error": {
"code": "device_not_found",
"message": "No device with that UUID exists in your organization",
"status": 404
}
}REST-API-Übersicht
Die Connection Server REST API ermöglicht den vollständigen programmatischen Zugriff auf Ihre Geräteflotte, Kommunikationsinfrastruktur und Analysetools. Sie folgt den RESTful-Konventionen mit JSON-Anfrage- und Antworttexten.
Authentifizierung
Tokenbasierte Authentifizierung. Login gibt ein Token zurück, das als Autorisierung: Token gesendet werden muss.<token> bei allen nachfolgenden Anfragen.
Benutzer
Benutzerkonten erstellen und verwalten. Der GET-Endpunkt /users/user gibt den aktuell authentifizierten Benutzer zurück.
Geräte
Geräte auflisten und überprüfen, Benutzer-Geräte-Zuordnungen verwalten, gerätespezifische Einstellungen und Status lesen und schreiben, Firmware- und Speicherabbilder verwalten sowie Protokolle und Absturzberichte empfangen.
CBBP-Proxy
Senden Sie beliebige CBBP-Befehle über den Server an ein Gerät. Der Server leitet den Befehl über die WLAN-Verbindung des Geräts weiter und sendet die Geräteantwort zurück. Die ausgehende Make-Antwort enthält außerdem eine CBBP-Nachricht, die das Gerät sofort ausführt.
Der Anfragetext ist ein CBBP-Befehls-Envelope. Das gespeicherte CBBPCommand-Objekt verfolgt den Zustellungsstatus: UNSET → SENT → RECEIVED oder TIMED_OUT.
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}Kanäle
Kanäle sind die grundlegenden Kommunikationsbausteine. Zu den Typen gehören ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService und ChannelRecorder.
Kommunikation
Aktive Kommunikationssitzungen initiieren und verwalten – ausgehende Anrufe, Videokonferenzen, Aufzeichnungen und Content-Streaming. Die Antwort auf eine ausgehende Anfrage enthält eine CBBPMessage, auf die das Gerät sofort reagiert.
Audiobrücke
Greifen Sie auf aufgezeichnete Brückengespräche zu, inklusive vollständiger Transkripte, Teilnehmerlisten und KI-generierter Zusammenfassungen. Unterstützt verschiedene Zusammenfassungsvorlagen (Besprechungsnotizen, Vorlesungsnotizen, Gesundheitswesen usw.) und die Generierung von TTS-Audio für Zusammenfassungen.
Gespräche
KI-gestützte Konversationen mit ChatGPT, Gemini oder der nativen Engine. Unterstützt mehrere Rollen (Arzt, Tutor, Mechaniker usw.) und eine paginierte Nachrichtenhistorie.
Inhalt
Durchsuchen und spielen Sie Audio-Streaming-Inhalte auf Ihren Geräten ab. Die Inhalte sind in einer Kategorienstruktur organisiert; beliebte Inhalte können nach Stadt, Region oder Land gefiltert werden.
Standorte
Geografische Koordinaten werden in ein strukturiertes Stadt-, Regions- und Länderobjekt aufgelöst. Wird von Geräten beim Erfassen von Kontextinformationen verwendet.
Push-Benachrichtigungen
Registrieren Sie eine mobile App, um FCM-Push-Benachrichtigungen zu erhalten. Unterstützt iOS, Android und Web.
Lagerung
Lädt die auf den Modellobjekten gespeicherten Dateien herunter und führt eine Bildhintergrundentfernung durch (gibt ein Base64-kodiertes Ergebnis zurück).
Massengutbetrieb
Führen Sie mehrere API-Operationen in einer einzigen HTTP-Anfrage aus. Übergeben Sie `single_transaction=true`, um alle Operationen in einer atomaren Transaktion zusammenzufassen – ein Fehler bei einem beliebigen Element führt zum Rollback des gesamten Batches.
Datum und Uhrzeit
Gibt das aktuelle Serverdatum und die Serverzeit in GMT+0 zurück. Erfordert keine Authentifizierung. Wird von Geräten zur Synchronisierung ihrer internen Uhr verwendet.
Com Badge Basic Protocol
CBBP ist ein leichtgewichtiges JSON-Befehlsprotokoll zur direkten Interaktion mit Verbindungsabzeichen. Es ermöglicht Ihnen die volle Kontrolle über alle Hardware- und Softwarefunktionen des Geräts.
Nachrichtenformat
Jede CBBP-Interaktion besteht aus einer an das Gerät gesendeten Befehlsnachricht und einer vom Gerät zurückgesendeten Ergebnisnachricht.
Das Feld „object“ in Anfrage und Antwort enthält befehlsspezifische Daten und kann weggelassen werden, wenn es nicht benötigt wird.
{
"command": "command_name",
"object": {
// optional command parameters
}
}{
"result": 0, // 0 = success, -1 = error
"detail": "ok", // human-readable status
"object": { // optional response data
// command-specific fields
}
}Transport
CBBP-Nachrichten können je nach Integrationsarchitektur über drei verschiedene Transportwege an ein Badge übermittelt werden.
Bluetooth (App)
Senden Sie CBBP-Befehle direkt von einer mobilen App über BLE. Das Gerät muss gekoppelt und in Reichweite sein.
Mobile SDKWLAN oder Bluetooth über Server
CBBP wird über die REST-API Proxy bereitgestellt – POST /devices//cbbp. Der Server leitet die Anfrage automatisch über WLAN oder Bluetooth an das Gerät weiter, je nachdem, wie der Badge verbunden ist. Dies ist die gängigste Methode für Backend-Integrationen.
REST-APIInterner Versand
Geräteinterne oder prozessübergreifende CBBP-Kommunikation. Wird von der Badge-Firmware verwendet, um Befehle zwischen internen Subsystemen weiterzuleiten.
Nur FirmwarePower-Befehle
Steuerung des Geräte-Energiezustands – Schlafmodus, Aufwachen, Neustart und Zurücksetzen auf Werkseinstellungen.
WLAN-Befehle
Konfigurieren Sie drahtlose Netzwerke, suchen Sie nach Zugangspunkten, überprüfen Sie den Verbindungsstatus und verwalten Sie gespeicherte Anmeldeinformationen.
Bluetooth-Befehle
Steuerung von BLE-Werbung, Pairing und Badge-zu-Badge-Kommunikation.
Befehle für Einstellungen
Gerätekonfiguration lesen und schreiben – Anzeigename, Zeitzone, Sprache und Funktionsflags.
Firmware-Befehle
OTA-Firmware-Updates auslösen, Update-Status prüfen und die aktuelle Firmware-Version auf dem Gerät abfragen.
Gerätebefehle
Gerätelebenszyklus, Authentifizierung, Konfiguration, Protokollierung, Status und Hardwaresteuerung.
Kommunikationsbefehle
Anrufe initiieren, Nachrichten senden, aktive Kommunikationssitzungen verwalten und die Aufzeichnung steuern.
Audiobefehle
Steuern Sie die Lautstärke des Lautsprechers, die Mikrofonverstärkung, Audioprofile und die Text-zu-Sprache-Wiedergabe.
LED-Befehle
Stellen Sie die LED-Farbe, Helligkeit und Animationsmuster der Badge-Kontrollleuchte ein.
Interne Befehle
Interne Dispatch-Befehle, die für die Kontextübermittlung, den Kanalverlauf, die Sprachausgabe und die Audiodekodierung verwendet werden.
Mobile Befehle
Befehle zur Koordinierung des Badges mit einer gekoppelten mobilen App – Push-Benachrichtigungen, App-Status-Synchronisierung und Deep Linking.