開發人員平台

建立喺
連線平台

兩個強大嘅 API — 一個用嚟管理裝置同通訊編排嘅 RESTful 伺服器 API ，同埋一個用嚟直接控制徽章嘅低級 CBBP 協定。

REST API 參考CBBP 協議
開放 API 3.0JSON / 休息藍牙 + WiFi網絡鉤支援
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

透過標準 HTTPS 進行完整嘅裝置生命週期管理 — 配置、配置、固件、通訊同分析。

探索 REST API →

CBBP 協議

Com Badge 基本協定 — 一個 JSON 命令協定，用嚟直接透過藍牙（應用程式）、 WiFi （伺服器代理）或者本地調度控制裝置。

探索 CBBP →

網絡鉤

訂閱即時裝置事件 — 通訊、狀態變更、位置更新 — 以 HTTP POST 有效負載形式傳送到你嘅端點。

探索網絡鉤 →

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.

開始啦

認證

連線 API 使用承載者憑證認證。所有請求都必須喺授權標題入面包含有效嘅 JWT 存取憑證。

獲得一個令牌

將你嘅憑證發佈去認證端點。你會收到一個短命嘅存取憑證同埋一個長命嘅刷新憑證。

用個代幣

喺每個要求入面加入憑證：

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

基本網址同版本控制

所有 API 端點都係用 /api/v1/ 版本化。基本網址取決於你嘅部署。

對於雲端托管嘅部署，請使用指派畀你嘅機構嘅地區端點。對於本地伺服器部署，請使用伺服器嘅主機名。

環境基本網址
雲（美國）https://beta.connection.app/api/v1
本地https://<your-server>/api/v1
內容類型
所有請求同回應機構都會用應用程式 / json 。喺要求同正文一齊加入內容類型：應用程式 / json 。

錯誤同狀態代碼

API 使用標準 HTTP 狀態碼。錯誤回應包括機器可讀嘅代碼同埋人類可讀嘅訊息。

地位意思
200成功
201建立咗
400錯誤嘅要求 — 無效嘅參數
401未經授權 — 遺失或者過期嘅憑證
403禁止 — 權限唔夠
404搵唔到
500內部伺服器錯誤
錯誤回應
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
REST API

REST API 概覽

連線伺服器 REST API 提供對你嘅裝置車隊、通訊基礎架構同分析嘅完整編程存取權。佢遵循 RESTful 準則同 JSON 請求/回應正文。

API 認證
用戶
裝置
頻道
溝通
音頻橋
對話
內容
地點
推送通知
儲存室
大量運作
日期同時間

認證

基於令牌嘅認證。登入會返回一個必須以授權形式發送嘅憑證：憑證<token>喺所有之後嘅要求上面。

POST/api/v1/login驗證用戶並收到認證憑證
POST/api/v1/login-device根據 UUID 同 MAC 地址驗證裝置
POST/api/v1/logout將當前嘅工作階段憑證無效化

用戶

建立同管理用戶帳戶。 GET /users/user 端點會返回目前已經驗證嘅用戶。

GET/api/v1/users/user擷取宜家登入咗嘅用戶個人檔案
POST/api/v1/users/user建立一個新嘅用戶帳戶
PATCH/api/v1/users/user/{uuid}更新用戶個人檔案（例如個人檔案圖片）

裝置

列出同檢查裝置、管理用戶同裝置關聯、讀取同寫入每個裝置嘅設定同狀態、處理固件同儲存映像，同埋接收記錄同當機報告。

GET/api/v1/devices/device列出所有裝置
GET/api/v1/devices/device/{uuid}攞到詳細嘅裝置資料，包括固件同設定
PUT/api/v1/devices/association/{uuid}更新用戶同裝置之間嘅關聯
DELETE/api/v1/devices/association/{uuid}移除用戶同裝置嘅關聯同埋儲存咗嘅設定
GET/api/v1/devices/device/{device_uuid}/settings列出儲存喺裝置嘅設定
POST/api/v1/devices/device/{device_uuid}/settings儲存裝置專用嘅設定
GET/api/v1/devices/device/{device_uuid}/status獲取裝置狀態（連線、電池、感應器、音頻狀態）
POST/api/v1/devices/device/{device_uuid}/status喺裝置發佈裝置狀態
GET/api/v1/devices/device/{device_uuid}/context列出儲存喺裝置嘅上下文值
POST/api/v1/devices/device/{device_uuid}/ingest-context喺裝置上面接收 GPS + WiFi 上下文
GET/api/v1/devices/firmware列出同特定硬件/軟件版本兼容嘅固件版本
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetch分塊攞固件映像
GET/api/v1/devices/language列出支援嘅裝置語言同聲音
GET/api/v1/devices/storage_image下載語言環境嘅自訂裝置儲存空間映像
POST/api/v1/devices/log喺裝置接收日誌檔案
POST/api/v1/devices/crash從裝置接收核心轉傳
PATCH/api/v1/devices/crash/{uuid}更新當機記錄

CBBP 代理

透過伺服器將任何 CBBP 指令傳送去裝置。伺服器會透過裝置嘅 WiFi 連線中繼指令，然後返回裝置回應。傳出嘅製造响應亦會嵌入一個 CBBPMessage , 裝置會即刻執行。

POST/api/v1/devices/device/{device_uuid}/cbbp透過伺服器向裝置發送 CBBP 指令
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}擷取之前發送嘅 CBBP 指令嘅狀態同回應

請求正文係一個 CBBP 命令信封。儲存咗嘅 CBBPCommand 對象會追蹤傳送狀態：未設定 → 傳送 → 接收或者 TIMED _ OUT 。

調查 GET /cbbp/ 嚟檢查裝置係咪收到同埋回應咗個指令。
要求 — 傳出訊息
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
回應 — CBBP 指令狀態
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

頻道

渠道係核心嘅通訊原語。類型包括頻道人、頻道群組、頻道聯絡人、頻道聯絡人編號、頻道外部編號、頻道服務同埋頻道記錄器。

GET/api/v1/channels/channel列出通道，可選按 object_type 篩選
POST/api/v1/channels/channel建立頻道（頻道群組、頻道聯絡人或者頻道外部號碼）
PATCH/api/v1/channels/channel/{uuid}更新頻道群組或者頻道聯絡人
DELETE/api/v1/channels/channel/{uuid}刪除一個頻道
DELETE/api/v1/channels/{uuid}刪除頻道群組
DELETE/api/v1/channels/by-type/{channelType}刪除所有特定類型嘅頻道（目前係頻道聯絡）
GET/api/v1/channels/association列出目前使用者嘅頻道關聯
POST/api/v1/channels/association要求同頻道建立關聯
PATCH/api/v1/channels/association/{uuid}接受、拒絕或者更新關聯設定
DELETE/api/v1/channels/association/{uuid}移除同頻道嘅關聯
GET/api/v1/channels/history攞到目前用戶嘅分頁頻道存取記錄
POST/api/v1/channels/history建立頻道記錄條目
GET/api/v1/channels/search按查詢字串同埋可選類型篩選器搜尋頻道

溝通

發起同埋管理主動通訊工作階段 — 撥出通話、 VCP 、錄音同埋內容串流。傳出嘅回應包括一個 CBBPMessage , 裝置會即刻喺呢個訊息上面操作。

POST/api/v1/communicate/outgoing-make啟動一個傳出頻道去頻道人、頻道群組、頻道聯絡人或者頻道聯絡人號碼
POST/api/v1/communicate/incoming-acceptance接受或者拒絕入嚟嘅頻道加入要求
POST/api/v1/communicate/close閂裝置上面目前有效嘅通訊頻道
POST/api/v1/communicate/vcp-activate喺伺服器同裝置上面啟動語音通訊協定（ VCP ）
POST/api/v1/communicate/vcp-deactivate停用 VCP ，返去任何之前嘅頻道
POST/api/v1/communicate/recording-activate喺伺服器同裝置上面啟動錄音模式
POST/api/v1/communicate/content-start打開音訊內容嘅串流頻道
POST/api/v1/communicate/request-vocalization為給定嘅文字生成 TTS 音頻，並且可以選擇性噉翻譯佢

音頻橋

存取錄製嘅橋樑對話，包括完整嘅轉錄文件、參與者名單同埋人工智能生成嘅摘要。支援多個摘要範本（會議筆記、課堂筆記、醫療保健等等）同埋 TTS 音頻生成嚟做摘要。

GET/api/v1/bridge/conversations列出所有橋樑對話
GET/api/v1/bridge/conversations/{uuid}攞到詳細嘅對話，包括記錄、參與者同埋摘要
POST/api/v1/bridge/conversations/{conversation_uuid}/summary為對話產生 AI 摘要
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audio為對話摘要產生音訊

對話

使用 ChatGPT 、 Gemini 或者原生引擎嘅人工智能對話會議。支援多個角色（醫生、導師、機械師等）同分頁訊息記錄。

GET/api/v1/conversations/conversation列出 AI 生成器工作階段，可以按角色同工具篩選
POST/api/v1/conversations/conversation建立一個新嘅 AI 對話環節
GET/api/v1/conversations/conversation/{uuid}擷取一個帶有可選摘要/離開更新嘅對話工作階段
DELETE/api/v1/conversations/conversation/{uuid}刪除對話環節
GET/api/v1/conversations/conversation/{uuid}/messages喺對話入面列出訊息
POST/api/v1/conversations/conversation/{uuid}/messages加入用戶訊息，然後收到 AI 回覆

內容

喺裝置上面瀏覽同埋播放串流音訊內容。內容係喺類別樹入面組織；熱門內容可以按城市、地區或者國家 / 地區篩選。

GET/api/v1/content/categories攞到一棵內容類別樹
GET/api/v1/content/content列出一個類別入面嘅可用內容
GET/api/v1/content/popular列出特定城市、地區或者國家 / 地區嘅熱門內容

地點

將地理座標解析為結構化嘅城市、地區同國家 / 地區物件。裝置喺攝取上下文嗰陣用。

POST/api/v1/location/determine解析城市、地區同國家 / 地區嘅緯度/經度

推送通知

註冊手機應用程式，接收 FCM 推送通知。支援 iOS 、 Android 同網絡目標。

POST/api/v1/push-notifications/push註冊手機應用程式，使用 FCM 推送通知（ iOS 、 Android 、網頁）

儲存室

下載儲存喺模型物件上面嘅檔案，然後執行圖片背景移除（返回 base64編碼嘅結果）。

GET/api/v1/storage/retrieve/{path}按路徑下載儲存咗嘅檔案
POST/api/v1/storage/remove-background喺圖片入面移除背景（返回 base64）

大量運作

喺一個 HTTP 請求入面執行多個 API 操作。傳送 single_transaction = true 就可以將所有操作包裝喺一個原子事務入面 — 任何項目嘅失敗都會回滾成個批次。

POST/api/v1/bulk喺單一請求中執行多個 API 操作，可以選擇作為單一原子事務

日期同時間

返回當前伺服器日期同時間，以 GMT + 0計。唔需要認證。裝置用嚟同步佢哋嘅內部時鐘。

GET/api/v1/current-datetime以 GMT + 0計返當前日期同時間
CBBP 協議

Com 徽章基本協定

CBBP 係一個輕量 JSON 命令協定，用嚟同連線徽章直接互動。佢畀你完全控制裝置上面嘅每個硬件同軟件功能。

訊息格式

每個 CBBP 互動都由發送到裝置嘅命令訊息同埋裝置返回嘅結果訊息組成。

請求同回應入面嘅對象欄位都會帶有指令專用嘅數據，而且喺唔需要嘅時候可以省略。

註冊嘅合作夥伴可以睇到完整嘅協議文件。 聯絡你嘅 Connection 業務代表或者聯絡我哋 developer@connectionbadge.com 要求存取完整嘅 CBBP 命令參考，包括完整嘅請求/响應架構、錯誤代碼同埋整合指南。
指令訊息
{
  "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
  }
}

交通

CBBP 訊息可以透過三種唔同嘅傳輸方式傳送到徽章，視乎你嘅整合架構而定。

藍牙（ App ）

透過 BLE 直接喺流動應用程式發送 CBBP 指令。需要將裝置配對同埋喺範圍內。

流動 SDK

透過伺服器嘅 WiFi 或者藍牙

透過 REST API 代理 CBBP — 發佈 / 裝置 / _ _ PH0 _ _ / cbbp 。伺服器會根據徽章嘅連接方式，透過 WiFi 或者藍牙自動路由去裝置。最常見嘅係後端整合。

REST API

內部調度

裝置上或者進程間嘅 CBBP 調度。徽章固件用嚟喺內部子系統之間路由指令。

只限固件

電源指令

控制裝置電源狀態 — 睡眠、喚醒、重新啟動同埋恢復出廠設定。

PowerReboot即刻重新啟動部裝置。
PowerDeepsleep進入深度睡眠（低功耗）模式。
FactoryReset清除所有設定，然後重設為出廠預設。

WiFi 指令

設定無線網絡、掃描 AP 、檢查連線狀態，同埋管理儲存咗嘅憑證。

WiFiScan掃描可用嘅 WiFi 接入點。
WiFiAPTest測試連接特定 WiFi 接入點。
WiFiAPJoin用提供嘅憑證加入 WiFi 接入點。

藍牙指令

控制 BLE 廣告、配對同埋徽章對徽章嘅通訊。

BTScanBT掃描經典藍牙裝置。
BTScanBLE掃描 BLE 裝置。
DeviceBLEServiceAvailable將 BLE 服務標記為可用。
DeviceBLEServiceUnavailable將 BLE 服務標記為唔可用。
DeviceBLEActive將 BLE 收音機設定為有效狀態。
DeviceBLEIdle將 BLE 收音機設定為閒置狀態。
DeviceBLEAdvChannelAdd將頻道加入 BLE 廣告有效負載。
DeviceBTScan啟動藍牙裝置掃描。
DeviceBTA2DStart開始藍牙 A2DP 音頻串流。
DeviceBTA2DEnd結束藍牙 A2DP 音頻串流。
DeviceBTNativeAssistStart啟動原生藍牙語音助理。
DeviceBTNativeAssistEnd結束原生藍牙語音助理。

設定指令

讀寫裝置設定 — 顯示名稱、時區、語言同埋功能旗號。

SettingsListGet將所有設定擷取為鍵值清單。
SettingsListSet一次過寫多個設定值。
SettingsGet按鍵攞到單一設定嘅值。
SettingsSet設定單一設定嘅值。
SettingsSend將目前嘅設定推送到伺服器。
SettingsClear清除特定嘅設定值。
SettingsErase清除所有儲存咗嘅設定。

固件指令

觸發 OTA 固件更新，檢查更新狀態，同埋查詢裝置上面嘅當前固件版本。

FirmwareCheck檢查有冇固件更新。
FirmwareUpdate開始 OTA 固件更新。
FirmwareValidate驗證下載咗嘅固件映像嘅完整性。

裝置指令

裝置生命週期、認證、配置、記錄、狀態同埋硬件控制。

NoOp冇手術 / 保持生命。
Test基本連線測試。
DeviceDateTime攞或者設定裝置日期同時間。
DeviceAuthenticate用伺服器驗證裝置。
DeviceConfigure將配置有效負載套用到裝置。
DevicePostConnectionTasks執行連線後初始化任務。
DeviceStorageLoad喺裝置上嘅儲存空間載入資料。
DeviceLoadCustomAudio將自訂音訊檔案載入裝置。
DeviceCoredumpSend上載崩潰核心轉傳去伺服器。
DeviceAttach將裝置附加到伺服器工作階段。
DeviceDetach將裝置同伺服器工作階段分離。
DeviceLogSend上載裝置記錄去伺服器。
DeviceConnectionTest測試伺服器連線。
DeviceStatusSend將裝置狀態推送到伺服器。
DeviceStatusGet攞到而家嘅裝置狀態。
DeviceInteraction觸發裝置互動事件。
DeviceSetAPIHost設定 API 伺服器主機。
DeviceTestMics執行麥克風自我測試。
HardwareI2CCommand將原始 I2C 指令發送去硬件外圍設備。

通訊指令

發起通話、發送訊息、管理主動通訊工作階段，同埋控制錄音。

CommunicateChannelJoin加入一個溝通渠道。
CommunicateChannelLeave留低一個溝通渠道。
CommunicateChannelChange轉去另一個頻道。
CommunicateChannelClose閂一個通訊渠道。
CommunicateReceiveIncoming通知裝置有傳入通訊。
CommunicateRequestOutgoing要求傳出通訊。
CommunicateVCPActivate啟動語音通訊協定工作階段。
CommunicateVCPDeactivate停用 VCP 工作階段。
CommunicateRecordingActivate開始錄製有效嘅通訊。
CommunicateIncomingAccept接受來電。
CommunicateIncomingReject拒絕來電。
CommunicateHFPCallStart開始藍牙 HFP 電話通話。
CommunicateHFPCallEnd結束藍牙 HFP 電話。
CommunicateContentStart開始將音訊內容串流到裝置。
CommunicateContentStop停止串流音訊內容。
SocketReceiveStatus接收 WebSocket 狀態更新。

音頻指令

控制喇叭音量、麥克風增益、音頻設定檔同埋文字轉語音播放。

AudioPlayStorage喺裝置上嘅儲存空間播放音訊檔案。
AudioPlayContent播放串流音訊內容。
AudioSetVolume設定喇叭輸出音量。

LED 指令

喺徽章指示燈上面設定 LED 顏色、亮度同動畫圖案。

DeviceIlluminationSet設定 LED 顏色同照明圖案。

內部指令

用嚟傳送上下文、頻道記錄、發聲同埋音頻解碼嘅內部調度指令。

InternalSendContext將上下文資料傳送去內部上下文處理程式。
InternalSendChannelHistory將頻道記錄傳送去內部處理程式。
InternalRequestVocalization喺內部要求文字轉語音發聲。
InternalHandleVocalizationRTP處理入嚟嘅發聲 RTP 流。
InternalDecodeAudio解碼入嚟嘅音頻流。

移動指令

用嚟將徽章同配對咗嘅流動應用程式協調嘅指令 — 推送通知、應用程式狀態同步同埋深層連結。

MobileServiceStatus向裝置報告流動服務狀態。 （手機 → 裝置）
MobileSocketOpen指示流動應用程式打開 WebSocket 連線。 （裝置 → 手機）
MobileSocketClose指示流動應用程式關閉 WebSocket 連線。 （裝置 → 手機）
MobileSocketStatus向流動應用程式報告 WebSocket 狀態。 （裝置 → 手機）
MobileReceiveStatus向流動應用程式報告接收狀態。 （裝置 → 手機）
MobileSocketUpdate將 WebSocket 數據更新傳送到流動應用程式。 （裝置 → 手機）
MobilePTTStart通知手機應用程式 PTT 傳輸已經開始。 （裝置 → 手機）
MobilePTTStop通知手機應用程式 PTT 傳輸已經結束。 （裝置 → 手機）
MobileContextSet喺流動應用程式上面設定上下文資料。 （裝置 → 手機）
MobileEcho用嚟測試流動連線嘅 Echo 指令。 （裝置 → 手機）

準備好建造未？

加入 Connection 開發人員社群，並存取沙盒裝置、 SDK 同埋專用支援。

聯絡我哋