​
产品概述

百融百语实时语音对话 JS SDK 是一款轻量级实时智能语音对话开发工具包。它封装了服务端连接、音频采集播放、对话控制等底层复杂逻辑，帮助开发者仅需 10 分钟即可为 Web 应用快速集成高质量的智能语音交互能力。 本 SDK 基于 WebRTC 技术构建，深度对接百语平台的智能硬件，支持与智能体进行端到端的实时语音对话，适用于陪伴硬件、智能客服、语音助手、智能外呼等多种业务场景。

​
一、接入前提

  1. 使用本 SDK 前，需先在百语平台创建智能体（Agent，又称 Robot），并通过 API 方式完成发布。发布成功后，可获取该智能体对应的唯一标识 robotKey 和访问令牌 robotToken，二者是 SDK 与智能体建立语音通话的核心身份凭证。
  2. 凭证获取指引：请参考《语音通话接入准备工作》完成操作。
安全提示：robotKey 和 robotToken 属于核心敏感信息，请务必妥善保管，严禁在客户端硬编码或公开泄露，避免造成信息泄露及不必要的计费损失。

​
二、快速入门

​
2.1 安装依赖

使用 pnpm（或 npm）安装 SDK： 
pnpm add @koi-video/voice-realtime-sdk

​
2.2 初始化客户端

创建 ChatClient 实例，传入身份凭证与用户信息完成初始化。 
import { ChatClient } from '@koi-video/voice-realtime-sdk';

const client = new ChatClient(
  {
    robotKey: process.env.ROBOT_KEY,
    robotToken: process.env.ROBOT_TOKEN,
  },
  {
    userName: 'demo-user-1',
  }
);
  • robotKey / robotToken：必填参数，用于 SDK 与百语平台的身份校验。
  • userName：必填参数，用于标识当前用户。请为每位用户分配唯一且不重复的标识，否则可能导致数据错乱或非预期运行结果。
  • 请确保页面运行在安全上下文中（HTTPS 或 localhost），否则麦克风权限与音频能力将无法正常使用。

​
2.3 事件监听

初始化完成后，可通过 on 方法注册事件回调，监听会话状态、消息与错误信息。 
import { VoiceEvents } from '@koi-video/voice-realtime-sdk';

// 会话创建成功
client.on(VoiceEvents.SESSION_CREATED, ({ sessionId }) => {
  console.log('会话已创建', sessionId);
});

// 会话正式开始
client.on(VoiceEvents.SESSION_STARTED, ({ sessionId }) => {
  console.log('会话已开始', sessionId);
});

// 会话结束
client.on(VoiceEvents.SESSION_ENDED, ({ sessionId, reason }) => {
  console.log('会话已结束', sessionId, reason);
});

// 用户侧语音转写消息
client.on(VoiceEvents.USER_MESSAGE, ({ content, segmentId, raw }) => {
  console.log('用户消息:', content, segmentId, raw);
});

// 机器人侧回复消息
client.on(VoiceEvents.ROBOT_MESSAGE, ({ content, segmentId, raw }) => {
  console.log('机器人消息:', content, segmentId, raw);
});


// 错误事件
client.on(VoiceEvents.ERROR, (err) => {
  console.error('错误:', err.code, err.message);
});

// 全局监听所有事件（便于调试与日志埋点）
client.on(VoiceEvents.ALL, (eventName, data) => {
  console.log('所有事件:', eventName, data);
});
  • 建议在调用 startVoiceChat 前完成所有事件监听器的注册，避免遗漏早期事件。
  • USER_MESSAGE 与 ROBOT_MESSAGE 事件中的 raw 字段承载了原始消息完整数据，结构示例如下： 
{
  "code": 0,
  "errMsg": "",
  "id": "66a68f46-2048-474c-b77c-d14c6f66a08d",
  "mimeType": "text/plain",
  "topic": "lk.transcription",
  "timestamp": 1772523409536,
  "role": "user",
  "text": "我是",
  "final": false,
  "payload": {
    "chat_id": 123,
    "transcript": "我是",
    "gender": "男性",
    "age": "20–40岁",
    "emotion": "缓和"
  },
  "encryptionType": 0
}
  • role：消息来源标识，user 表示用户语音识别结果，llm 表示机器人回复文本。
  • final：语句结束标识，false 为识别过程中的中间增量片段，true 表示该句识别完成。

​
2.4 启动语音对话

调用 startVoiceChat 方法发起通话，该方法为异步函数，成功后返回会话 ID。 
try {
  const sessionId = await client.startVoiceChat();
  console.log('语音对话已启动，会话ID:', sessionId);
} catch (error) {
  console.error('启动失败', error);
}
  • 调用后 SDK 会自动向浏览器申请麦克风权限，并建立 RTC 连接。
  • 首次调用时浏览器会弹出权限申请弹窗，需用户手动授权。
  • 在 iOS Safari 环境下，该方法必须由用户交互事件（如点击按钮）触发，否则会被浏览器拦截。
  • 若用户拒绝麦克风权限，建议在页面上给出明确指引，引导用户在浏览器设置中开启权限。

​
2.5 控制对话流程

会话过程中，可通过以下方法控制对话状态与音频采集。 
// 打断机器人当前播报
client.interrupt();

// 静音
await client.setAudioEnabled({ bool: false });

// 取消静音
await client.setAudioEnabled({ bool: true });

// 结束语音对话，释放连接资源
await client.stopVoiceChat();
  • interrupt()：主动中断机器人正在进行的语音回复，调用后机器人会停止当前播报。
  • setAudioEnabled()：异步方法，需使用 await 等待操作完成；静音状态下麦克风保持采集，但是向服务端发送的是静音数据。
  • stopVoiceChat()：异步方法，调用后会关闭 RTC 连接并释放相关资源；如需重新发起对话，需再次调用 startVoiceChat()。

​
2.6 完整示例

以下为从初始化到结束通话的完整接入示例： 
import { ChatClient, VoiceEvents } from '@koi-video/voice-realtime-sdk';

// 1. 初始化客户端
const client = new ChatClient(
  {
    robotKey: process.env.ROBOT_KEY,
    robotToken: process.env.ROBOT_TOKEN,
  },
  {
    userName: 'demo-user-1',
  }
);

// 2. 注册事件监听
client.on(VoiceEvents.SESSION_CREATED, ({ sessionId }) => {
  console.log('SESSION_CREATED', sessionId);
});

client.on(VoiceEvents.SESSION_STARTED, ({ sessionId }) => {
  console.log('SESSION_STARTED', sessionId);
});

client.on(VoiceEvents.SESSION_ENDED, ({ sessionId, reason }) => {
  console.log('SESSION_ENDED', sessionId, reason);
});

client.on(VoiceEvents.USER_MESSAGE, ({ content, segmentId, raw }) => {
  console.log('用户:', content, segmentId, raw);
});

client.on(VoiceEvents.ROBOT_MESSAGE, ({ content, segmentId, raw }) => {
  console.log('机器人:', content, segmentId, raw);
});

client.on(VoiceEvents.INTERRUPT, ({ sessionId }) => {
  console.log('打断', sessionId);
});

client.on(VoiceEvents.AUDIO_MUTED, ({ sessionId }) => {
  console.log('静音', sessionId);
});

client.on(VoiceEvents.AUDIO_UNMUTED, ({ sessionId }) => {
  console.log('取消静音', sessionId);
});

client.on(VoiceEvents.ERROR, (err) => {
  console.error('错误:', err.code, err.message);
});

client.on(VoiceEvents.ALL, (eventName, data) => {
  console.log('所有事件:', eventName, data);
});

// 3. 启动对话
const startChat = async () => {
  try {
    const sessionId = await client.startVoiceChat();
    console.log('对话已启动，会话ID:', sessionId);
  } catch (error) {
    console.error('启动失败', error);
  }
};

// 示例：5秒后打断，10秒后结束对话
setTimeout(() => {
  client.interrupt();
}, 5000);

setTimeout(async () => {
  await client.stopVoiceChat();
  console.log('对话已结束');
}, 10000);

startChat();

​
2.7 VoiceEvents 常量说明

常量名触发时机载荷字段
SESSION_CREATEDHTTP 建连成功、会话就绪时触发sessionId
SESSION_ENDED用户主动结束、RTC 异常断开或会话正常结束时触发sessionId、reason
USER_MESSAGE收到用户侧语音转写流消息时触发sessionId、content、segmentId、timestamp
ROBOT_MESSAGE收到机器人侧回复流消息时触发sessionId、content、segmentId、timestamp
INTERRUPT打断操作生效、机器人停止播报时触发sessionId
ERROR接口请求、RTC 连接、数据解析等任意环节发生错误时触发code、message、sessionId
AUDIO_MUTED调用静音操作完成后触发sessionId
AUDIO_UNMUTED调用取消静音操作完成后触发sessionId
ALL监听所有事件，可用于统一日志埋点与调试eventName、data

​
三、导出模块说明

模块名称类型描述
ChatClient类语音通话核心客户端类，负责会话管理、音频控制、事件派发等核心能力
VoiceEvents常量对象所有事件名称的常量集合，推荐使用常量替代硬编码字符串，避免拼写错误