验证
Connection API 使用 Bearer 令牌认证。所有请求都必须在 Authorization 标头中包含有效的 JWT 访问令牌。
获取代币
将您的凭据 POST 到身份验证端点。您将收到一个有效期较短的 access_token 和一个有效期较长的 refresh_token。
使用令牌
在每个请求中都包含令牌：
{
"email": "admin@yourorg.com",
"password": "••••••••"
}{
"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 提供对设备群、通信基础设施和分析功能的完整编程访问权限。它遵循 RESTful 规范，使用 JSON 请求/响应正文。
验证
基于令牌的身份验证。登录会返回一个令牌，该令牌必须作为 Authorization: Token 发送。<token>对所有后续请求。
用户
创建和管理用户帐户。GET /users/user 端点返回当前已验证的用户。
设备
列出和检查设备，管理用户-设备关联，读取和写入每个设备的设置和状态，处理固件和存储映像，并接收日志和崩溃报告。
CBBP代理
通过服务器向设备发送任何 CBBP 命令。服务器通过设备的 WiFi 连接转发该命令，并返回设备的响应。发送的响应中还嵌入了一个 CBBPMessage，设备会立即执行该消息。
请求正文是一个 CBBP 命令信封。存储的 CBBPCommand 对象跟踪传递状态：未设置 → 已发送 → 已接收 或 超时。
{
"outgoingMessage": {
"command": "WiFiScan"
}
}{
"uuid": "a3f2...",
"status": "SENT",
"device": "d7f3a1b2-...",
"dateSent": "2025-09-15T14:22:01Z",
"outgoingMessage": { /* echoed */ },
"incomingMessage": null
}频道
通道是核心通信原语。类型包括 ChannelPeople、ChannelGroup、ChannelContact、ChannelContactNumber、ChannelExternalNumber、ChannelService 和 ChannelRecorder。
沟通
发起并管理活跃的通信会话——包括拨出电话、视频会议、录音和内容流传输。拨出电话的响应包含一个 CBBPMessage，设备会立即对此做出反应。
音频桥
访问已录制的桥接对话，包括完整文字稿、参与者列表和人工智能生成的摘要。支持多种摘要模板（会议记录、课堂记录、医疗保健记录等）以及用于生成摘要的文本转语音（TTS）音频。
对话
使用 ChatGPT、Gemini 或原生引擎进行 AI 驱动的对话会话。支持多种角色（医生、家教、技工等）和分页消息历史记录。
内容
在设备上浏览和播放流媒体音频内容。内容按类别树状结构组织；热门内容可按城市、地区或国家/地区筛选。
地点
将地理坐标解析为结构化的城市、地区和国家对象。供设备在获取上下文信息时使用。
推送通知
注册移动应用即可接收 FCM 推送通知。支持 iOS、Android 和网页平台。
贮存
下载存储在模型对象上的文件，并运行图像背景去除（返回 base64 编码的结果）。
散装作业
在单个 HTTP 请求中执行多个 API 操作。传递 single_transaction=true 参数可将所有操作封装在一个原子事务中——任何一个操作失败都会回滚整个批次。
日期和时间
返回服务器当前日期和时间（GMT+0）。无需身份验证。供设备同步其内部时钟。
通信徽章基本协议
CBBP 是一种轻量级的 JSON 命令协议，用于与 Connection 徽章进行直接交互。它使您能够完全控制设备上的所有硬件和软件功能。
消息格式
每次 CBBP 交互都包含一条发送到设备的命令消息和一条设备返回的结果消息。
请求和响应中的 object 字段包含命令特定的数据，在不需要时可以省略。
{
"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 分发。徽章固件使用此方法在内部子系统之间路由命令。
仅固件电源指令
控制设备电源状态——睡眠、唤醒、重启和恢复出厂设置。
WiFi 指令
配置无线网络、扫描接入点、检查连接状态和管理已保存的凭据。
蓝牙命令
控制 BLE 广播、配对和徽章间通信。
设置命令
读取和写入设备配置——显示名称、时区、语言和功能标志。
固件命令
触发 OTA 固件更新，检查更新状态，并查询设备上的当前固件版本。
设备命令
设备生命周期、身份验证、配置、日志记录、状态和硬件控制。
通信指令
发起通话、发送消息、管理进行中的通信会话和控制录音。
语音命令
控制扬声器音量、麦克风增益、音频配置文件和文本转语音播放。
LED指令
设置徽章指示灯的 LED 颜色、亮度和动画模式。
内部指令
用于上下文传递、频道历史记录、语音和音频解码的内部调度命令。
移动指令
用于将徽章与配对的移动应用程序协调的命令——推送通知、应用程序状态同步和深度链接。