AI 语音控制台

POST 会话握手接口 (Handshake)

第三方服务端在为客户端分配语音通话连接前，通过此接口申请受保护的会话凭证：

URL: /api/v1/sessions
Headers:
  Content-Type: application/json
  X-Voice-API-Key: <您的API_KEY>

Request Body:
{
  "userId": "dev_user_001",
  "displayName": "第三方测试用户",
  "sessionConfig": {
    "greeting": "欢迎使用实时助手",
    "intents": [
      { "code": "ACT001", "description": "挂号" },
      { "code": "ACT002", "description": "缴费" }
    ]
  }
}

Response Body (200 OK):
{
  "streamUrl": "wss://media-gateway.com",
  "streamToken": "ey..." // 会话临时媒体Token
}

DataChannel 下行控制指令格式

当 AI 语音交互匹配到预设的意图时，系统会向客户端广播下行 DataChannel 控制指令数据包。格式如下：

{
  "type": "command",
  "name": "ACT001", // 触发的意图指令代码
  "payload": {
    // 对应操作附带的动态参数
  },
  "timestamp": 1780040000000
}

另外，当通话正常结束挂机或用户道别时，系统会统一下发 "hangup" 指令，客户端捕获该指令时应自动挂机断连。

WebRTC 语音流与传输原理

1. 建立核心媒体隧道 (WebSocket):
   SDK 内部会向流媒体网关建立安全连接。
   此连接仅用于传输加密凭证与媒体协商信息。

2. 语音发送 (上行流):
   SDK 获取麦克风权限后，将采集并压缩音频，
   通过加密实时通道发送给云端 AI 引擎。

3. 语音接收 (下行流):
   当智能助手说话时，SDK 会监听到下行媒体流到达事件，
   自动将音频附加到浏览器后台媒体播放器并进行播放。

4. 实时文本与控制指令:
   语音转写结果、状态同步与控制指令通过实时数据通道无感下发。

ESM SDK 客户端前端集成示例

第三方开发者无需关心 WebRTC 协商细节，直接使用混淆版 SDK 几行代码即可极速集成：

import { VoiceSession } from "./sdk/voice-agent-sdk.js";

const session = new VoiceSession({
  apiHost: "https://your-api.com",
  apiKey: "sk-af9bc06a0c450109ca7ba14dc77d2bc8",
  userId: "user_123",
  sessionConfig: {
    greeting: "您好！",
    intents: [
      { "code": "ACT001", "description": "挂号" }
    ]
  }
});

// 监听状态改变与对话文本
session.on("status", (s) => console.log(s.label));
session.on("transcription", (t) => console.log(t.text));

// 监听下行控制指令动作
session.on("command", (cmd) => {
  if (cmd.name === "ACT001") {
    // 执行本地跳转挂号页面动作
  }
});

// 启动连接
await session.start();