Uwierzytelnianie
Interfejs API połączenia korzysta z uwierzytelniania za pomocą tokenu Bearer. Wszystkie żądania muszą zawierać prawidłowy token dostępu JWT w nagłówku Authorization.
Zdobądź token
Wyślij swoje dane uwierzytelniające do punktu końcowego uwierzytelniania. Otrzymasz krótkotrwały access_token i dłuższy refresh_token.
Użyj tokena
Dołącz token do każdego żądania:
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"access_token": "eyJhbG...",
"refresh_token": "dGhpcw...",
"expires_in": 3600,
"token_type": "Bearer"
}Podstawowy adres URL i wersjonowanie
Wszystkie punkty końcowe API są wersjonowane w katalogu /api/v1/. Podstawowy adres URL zależy od wdrożenia.
W przypadku wdrożeń hostowanych w chmurze należy użyć regionalnego punktu końcowego przypisanego do organizacji. W przypadku wdrożeń na serwerze lokalnym należy użyć nazwy hosta serwera.
| Środowisko | Podstawowy adres URL |
|---|---|
| Chmura (USA) | https://beta.connection.app/api/v1 |
| Na miejscu | https://<your-server>/api/v1 |
Wszystkie treści żądań i odpowiedzi korzystają z pliku application/json. Do żądań z treścią należy dołączyć Content-Type: application/json.
Błędy i kody stanu
API korzysta ze standardowych kodów stanu HTTP. Odpowiedzi na błędy zawierają kod czytelny dla maszyny i komunikat czytelny dla człowieka.
| Status | Oznaczający |
|---|---|
| 200 | Sukces |
| 201 | Stworzony |
| 400 | Błędne żądanie — nieprawidłowe parametry |
| 401 | Nieautoryzowany — brakujący lub wygasły token |
| 403 | Zabronione — niewystarczające uprawnienia |
| 404 | Nie znaleziono |
| 500 | Wewnętrzny błąd serwera |
{
"error": {
"code": "device_not_found",
"message": "No device with that UUID exists in your organization",
"status": 404
}
}Przegląd interfejsu API REST
Interfejs API REST serwera połączeń zapewnia pełny, programowy dostęp do floty urządzeń, infrastruktury komunikacyjnej i analityki. Jest zgodny z konwencjami RESTful z treściami żądania/odpowiedzi w formacie JSON.
Uwierzytelnianie
Uwierzytelnianie oparte na tokenach. Logowanie zwraca token, który należy wysłać jako Autoryzacja: Token<token> na wszystkie kolejne żądania.
Użytkownicy
Twórz i zarządzaj kontami użytkowników. Punkt końcowy GET /users/user zwraca aktualnie uwierzytelnionego użytkownika.
Urządzenia
Twórz listy i sprawdzaj urządzenia, zarządzaj powiązaniami użytkownik–urządzenie, odczytuj i zapisuj ustawienia i statusy poszczególnych urządzeń, obsługuj obrazy oprogramowania sprzętowego i pamięci masowej oraz odbieraj dzienniki i raporty o awariach.
Pełnomocnik CBBP
Wyślij dowolne polecenie CBBP do urządzenia przez serwer. Serwer przekazuje polecenie przez połączenie Wi-Fi urządzenia i zwraca odpowiedź urządzenia. Odpowiedź outgoing-make zawiera również komunikat CBBPMessage, który urządzenie natychmiast wykonuje.
Treść żądania to koperta polecenia CBBP. Przechowywany obiekt CBBPCommand śledzi status dostarczenia: UNSET → SENT → RECEIVED lub TIMED_OUT.
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}Kanały
Kanały to podstawowe prymitywy komunikacyjne. Do typów należą: ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService i ChannelRecorder.
Komunikacja
Inicjuj i zarządzaj aktywnymi sesjami komunikacyjnymi — połączeniami wychodzącymi, VCP, nagrywaniem i strumieniowaniem treści. Odpowiedź typu „outgoing-make” zawiera komunikat CBBPMessage, na który urządzenie reaguje natychmiast.
Mostek audio
Uzyskaj dostęp do nagranych rozmów brydżowych, w tym pełnych transkryptów, list uczestników i podsumowań generowanych przez sztuczną inteligencję. Obsługuje wiele szablonów podsumowań (notatki ze spotkań, zajęć, opieki zdrowotnej itp.) oraz generowanie dźwięku TTS do podsumowań.
Rozmowy
Sesje konwersacyjne oparte na sztucznej inteligencji, wykorzystujące ChatGPT, Gemini lub natywny silnik. Obsługuje wiele profili (lekarz, korepetytor, mechanik itp.) i podzieloną na strony historię wiadomości.
Treść
Przeglądaj i odtwarzaj strumieniowane treści audio na urządzeniach. Treści są uporządkowane w drzewie kategorii; popularne treści można filtrować według miasta, regionu lub kraju.
Lokalizacje
Przekształca współrzędne geograficzne w ustrukturyzowany obiekt miasta, regionu i kraju. Używane przez urządzenia podczas pobierania kontekstu.
Powiadomienia push
Zarejestruj aplikację mobilną, aby otrzymywać powiadomienia push FCM. Obsługuje systemy iOS, Android i przeglądarki internetowe.
Składowanie
Pobierz pliki zapisane w obiektach modelu i uruchom usuwanie tła obrazu (zwraca wynik zakodowany w formacie base64).
Operacje masowe
Wykonuj wiele operacji API w jednym żądaniu HTTP. Przekaż parametr single_transaction=true, aby zawrzeć wszystkie operacje w jednej transakcji atomowej — błąd dowolnego elementu powoduje wycofanie całej partii.
Data i godzina
Zwraca aktualną datę i godzinę serwera w formacie GMT+0. Nie wymaga uwierzytelnienia. Używany przez urządzenia do synchronizacji zegara wewnętrznego.
Podstawowy protokół Com Badge
CBBP to lekki protokół poleceń JSON do bezpośredniej interakcji z identyfikatorami połączeń. Zapewnia pełną kontrolę nad wszystkimi funkcjami sprzętowymi i programowymi urządzenia.
Format wiadomości
Każda interakcja CBBP składa się z komunikatu polecenia wysłanego do urządzenia i komunikatu wynikowego zwróconego przez urządzenie.
Pole obiektu zarówno w żądaniu, jak i odpowiedzi zawiera dane specyficzne dla polecenia i może zostać pominięte, jeśli nie jest potrzebne.
{
"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
Wiadomości CBBP mogą być dostarczane do identyfikatora za pośrednictwem trzech różnych transportów, w zależności od architektury integracji.
Bluetooth (aplikacja)
Wysyłaj polecenia CBBP bezpośrednio z aplikacji mobilnej przez BLE. Wymaga sparowania urządzenia i jego zasięgu.
Mobilny zestaw SDKWiFi lub Bluetooth przez serwer
Przekaż CBBP przez API REST — POST /devices//cbbp. Serwer automatycznie przekierowuje do urządzenia przez Wi-Fi lub Bluetooth, w zależności od sposobu połączenia identyfikatora. Najczęściej spotykane w przypadku integracji back-endowych.
Interfejs API RESTDyspozytornia wewnętrzna
Dystrybucja CBBP na urządzeniu lub międzyprocesowa. Używana przez oprogramowanie sprzętowe odznaki do kierowania poleceniami między wewnętrznymi podsystemami.
Tylko oprogramowanie sprzętowePolecenia mocy
Kontroluj stan zasilania urządzenia — uśpienie, wybudzenie, ponowne uruchomienie i przywrócenie ustawień fabrycznych.
Polecenia WiFi
Konfiguruj sieci bezprzewodowe, skanuj punkty dostępowe, sprawdzaj stan połączenia i zarządzaj zapisanymi danymi uwierzytelniającymi.
Polecenia Bluetooth
Kontroluj reklamy BLE, parowanie i komunikację między odznakami.
Polecenia ustawień
Odczyt i zapis konfiguracji urządzenia — nazwy wyświetlanej, strefy czasowej, języka i flag funkcji.
Polecenia oprogramowania sprzętowego
Wyzwalaj aktualizacje oprogramowania sprzętowego OTA, sprawdzaj status aktualizacji i pytaj o aktualną wersję oprogramowania sprzętowego w urządzeniu.
Polecenia urządzenia
Cykl życia urządzenia, uwierzytelnianie, konfiguracja, rejestrowanie, status i kontrola sprzętu.
Polecenia komunikacyjne
Nawiązuj połączenia, wysyłaj wiadomości, zarządzaj aktywnymi sesjami komunikacyjnymi i kontroluj nagrywanie.
Polecenia audio
Kontroluj głośność głośnika, wzmocnienie mikrofonu, profile audio i odtwarzanie tekstu na mowę.
Polecenia LED
Ustaw kolor diody LED, jasność i wzory animacji dla kontrolki identyfikatora.
Polecenia wewnętrzne
Wewnętrzne polecenia dyspozytorskie używane do dostarczania kontekstu, historii kanału, wokalizacji i dekodowania dźwięku.
Polecenia mobilne
Polecenia umożliwiające skoordynowanie odznaki ze sparowaną aplikacją mobilną — powiadomienia push, synchronizacja stanu aplikacji i głębokie linki.