開發者平台

在此基礎上繼續
連接平台

兩個強大的 API——一個用於設備管理和通訊協調的 RESTful 伺服器 API，以及一個用於直接徽章控制的底層 CBBP 協定。

REST API 參考CBBP協定
OpenAPI 3.0JSON/REST藍牙+WiFiWebhook 支持
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 有效負載的形式傳送到您的端點。

探索 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.

入門

驗證

Connection API 使用 Bearer 令牌認證。所有請求都必須在 Authorization 標頭中包含有效的 JWT 存取權杖。

獲取代幣

將您的憑證 POST 到身分驗證端點。您將收到一個有效期較短的 access_token 和一個有效期較長的 refresh_token。

使用令牌

在每個請求中都包含令牌：

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"
}

基本 URL 和版本控制

所有 API 端點的版本均位於 /api/v1/ 下。基本 URL 取決於您的部署情況。

對於雲端託管部署，請使用指派給您組織的區域端點。對於本機伺服器部署，請使用伺服器的主機名稱。

環境基本 URL
雲端（美國）https://beta.connection.app/api/v1
本地部署https://<your-server>/api/v1
內容類型
所有請求和回應體均使用 application/json 格式。對於帶有請求體的請求，請新增 Content-Type: application/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 驗證
使用者
裝置
頻道
溝通
音訊橋
對話
內容
地點
推播通知
貯存
散裝作業
日期和時間

驗證

基於令牌的身份驗證。登入會傳回一個令牌，該令牌必須以 Authorization: Token 傳送。<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 物件追蹤傳遞狀態：未設定 → 已傳送 → 已接收 或 逾時。

Poll GET /cbbp/ 檢查設備是否已收到並回應指令。
請求 — 發送訊息
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
回應 — CBBPCommand 狀態
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

頻道

頻道是核心通訊原語。類型包括 ChannelPeople、ChannelGroup、ChannelContact、ChannelContactNumber、ChannelExternalNumber、ChannelService 和 ChannelRecorder。

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透過查詢字串和可選類型篩選器搜尋頻道

溝通

發起並管理活躍的通訊會話－包括撥出電話、視訊會議、錄音和內容串流。撥出電話的回應包含一個 CBBPMessage，設備會立即對此做出反應。

POST/api/v1/communicate/outgoing-make向 ChannelPeople、ChannelGroup、ChannelContact 或 ChannelContactNumber 發起外發管道。
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為對話產生人工智慧摘要
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audio產生對話摘要音頻

對話

使用 ChatGPT、Gemini 或原生引擎進行 AI 驅動的對話會話。支援多種角色（醫生、家教、技工等）和分頁訊息歷史記錄。

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協定

通信徽章基本協議

CBBP 是一種輕量級的 JSON 命令協議，用於與 Connection 徽章進行直接互動。它使您能夠完全控制設備上的所有硬體和軟體功能。

訊息格式

每次 CBBP 互動都包含一條傳送到裝置的命令訊息和一則裝置傳回的結果訊息。

請求和回應中的 object 欄位包含命令特定的數據，在不需要時可以省略。

完整的協議文件可供註冊合作夥伴查閱。 請聯絡您的 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 訊息可以透過三種不同的傳輸方式傳遞到徽章。

藍牙（應用程式）

透過藍牙低功耗技術，直接從行動應用程式發送CBBP命令。設備需要已配對且在有效範圍內。

行動 SDK

透過伺服器使用 WiFi 或藍牙

透過 REST API 代理 CBBP — POST /devices//cbbp。伺服器會根據徽章的連接方式自動透過 WiFi 或藍牙路由到裝置。最常用於後端整合。

REST API

內部調度

設備端或進程間 CBBP 分發。徽章韌體使用此方法在內部子系統之間路由命令。

僅韌體

電源指令

控制設備電源狀態－睡眠、喚醒、重新啟動和恢復出廠設定。

PowerReboot立即重啟設備。
PowerDeepsleep進入深度睡眠（低功耗）模式。
FactoryReset清除所有配置並恢復原廠設定。

WiFi 指令

設定無線網路、掃描存取點、檢查連線狀態和管理已儲存的憑證。

WiFiScan掃描可用的WiFi接入點。
WiFiAPTest測試與特定WiFi接入點的連線情況。
WiFiAPJoin使用提供的憑證連接到 WiFi 存取點。

藍牙命令

控制 BLE 廣播、配對和徽章間通訊。

BTScanBT掃描經典藍牙裝置。
BTScanBLE掃描藍牙低功耗裝置。
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用於測試行動網路連線的回顯指令。 （設備 → 行動裝置）

準備開工了嗎？

加入 Connection 開發者社區，即可獲得沙盒設備、SDK 和專屬支援。

聯絡我們