​
产品概述

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

​
一、接入前提

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

​
二、SDK 基础信息

​
2.1 SDK 获取与文件说明

SDK 以 AAR 包形式分发，最新版本可从官方发布页下载。
名称类型
BR_AI_Voice_RTCaar

​
2.2 兼容性说明

项说明
Android 系统minSdk 版本为 24，对应 Android 7.0 及以上
开发语言工程使用 Kotlin 开发；AAR 包已包含所需的 Kotlin 及协程依赖，无需额外引入
ABI 架构支持 arm64-v8a、armeabi-v7a 架构

​
三、SDK 快速集成

​
3.1 加载 SDK

将从官方发布地址下载的 BR_AI_Voice_RTC_x.x.x.aar 文件放入宿主模块的 libs/ 目录下，然后在宿主工程的 build.gradle.kts 文件中添加如下依赖引用： 
dependencies {
    implementation(files("libs/BR_AI_Voice_RTC_x.x.x.aar"))
}
注意：AAR 包内部已携带 consumer-rules.pro 消费者混淆规则，当宿主工程启用 R8 / 混淆功能时，这些规则会自动合并到宿主的混淆配置中，无需手动添加。

​
3.2 权限配置

说明：AAR 包的 AndroidManifest.xml 中已声明 SDK 所需的基础权限，宿主工程通常无需重复声明。但从 Android 6.0（API 23）开始，部分特殊权限需宿主工程在运行时动态申请；SDK 会对权限进行校验，若权限缺失，将通过 ChatEvent.ERROR 事件返回对应错误信息。
  • SDK 内部会校验 RECORD_AUDIO 麦克风权限，宿主工程需在运行时动态申请，权限声明如下：
<uses-permission android:name="android.permission.RECORD_AUDIO" />
  • 在 Android 12（API 31）及以上版本，可根据业务需求按需申请以下可选权限（与蓝牙路由、部分机型音频场景相关，仅在需要使用蓝牙耳机或特定音频路由能力时开启）：
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
  • AAR 包中已内置的权限配置如下（宿主无需重复声明）：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- <uses-permission android:name="android.permission.BLUETOOTH" /> -->
<!-- <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> -->
<!-- <uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> -->
<!-- <uses-permission android:name="android.permission.READ_PHONE_STATE" /> -->

​
3.3 代码示例

集成顺序：先确保获取所需权限 → 构造 ChatClient 实例 → 注册事件监听 → 调用 startVoiceChat() 启动语音交互；退出页面时，需调用 stopVoiceChat() 结束会话并调用 removeAll() 取消所有监听，避免内存泄漏。 
// 1. 确保已获取所需权限后，构造 ChatClient 实例
val client = ChatClient(
    context = applicationContext,
    robotKey = "<Robot-Key>",      // 替换为从百语平台获取的 robotKey
    robotToken = "<Robot-Token>", // 替换为从百语平台获取的 robotToken
    userName = "<user_name>"      // 替换为当前用户的唯一标识
)

// 2. 按需监听事件，onAny 方法可监听全部事件
client.on(ChatEvent.ERROR) { _, data ->
    if (data is ErrorMessage) {
        // 处理错误信息：data.code（错误码） / data.errMsg（错误描述）
    }
}

client.on(ChatEvent.ROBOT_MESSAGE) { _, data ->
    if (data is ChannelMessage) {
        // 处理机器人消息：data.text（解析后的文本）, data.rawJson（原始 JSON 字符串）等
    }
}

// 可根据业务需求，继续监听其他所需事件...

// 3. 启动语音交互
client.startVoiceChat()

// 4. 退出页面时，结束会话并释放监听
client.stopVoiceChat()
client.removeAll()

​
四、SDK 主要方法

所有核心方法均封装在 com.brgroup.voice.ai.ChatClient 类中，调用前需确保已成功构造 ChatClient 实例。

​
4.1 初始化语音交互管理器

通过构造函数创建 ChatClient 实例，完成初始化。 
ChatClient(
    context: Context,
    robotKey: String,
    robotToken: String,
    userName: String
)
参数说明：
  • robotKey / robotToken：用于 SDK 与百语平台智能体的身份验证，需从百语平台获取。
  • userName：用于标识当前用户，需为每位用户分配唯一且不重复的标识；若不同用户共用同一标识，可能导致数据错乱或非预期运行结果。

​
4.2 启动语音会话

fun startVoiceChat()
功能说明：发起与智能体的实时语音会话，建立 RTC 连接。调用前需确保已获取麦克风权限且 ChatClient 实例初始化成功。

​
4.3 结束语音会话

fun stopVoiceChat()
功能说明：主动结束当前语音会话，释放 RTC 连接及相关资源。建议在页面销毁前调用。

​
4.4 打断机器人回复及播报

fun interrupt(): Boolean
功能说明：主动打断机器人正在进行的语音回复和播报。返回值为 Boolean，失败时返回 false，且可能伴随 ERROR 事件（如错误码 3011、3009 等）。

​
4.5 麦克风开关控制

fun setAudioEnabled(enabled: Boolean)
功能说明：开启或关闭本地麦克风音频采集。操作成功时，会触发 AUDIO_MUTED（关闭）或 AUDIO_UNMUTED（开启）事件。

​
4.6 获取 SDK 版本号

fun getSdkVersion(): String
功能说明：获取当前集成的 SDK 版本号，返回值为版本号字符串，如 "1.0.0"。

​
五、SDK 事件回调

SDK 所有事件均通过 ChatClient.on(ChatEvent, ChatEventListener) 方法订阅，也可使用 onAny 方法监听全部事件，便于统一处理。 注意：所有事件均在主线程（Handler(Looper.getMainLooper())）派发，可直接在回调中更新 UI。

​
5.1 ChatEvent 枚举（核心事件）

事件data 常见类型说明
ERRORErrorMessage结构化错误，包含 code 和 errMsg
SESSION_STARTED通常为 null本端进房成功（RTC 回调）
SESSION_ENDED通常为 null会话结束流程完成
ROBOT_MESSAGEChannelMessage机器人侧字幕 / 消息
USER_MESSAGEChannelMessage用户侧字幕 / 消息
AUDIO_MUTED / AUDIO_UNMUTED通常为 null麦克风关闭 / 打开结果
ROBOT_JOINED / ROBOT_LEFT通常为 null远端用户进房 / 离房（业务上可视为机器人链路）

​
5.2 ChannelMessage 说明

ChannelMessage 为消息数据模型，包含解析后的字段及原始 JSON 字符串 rawJson，核心字段说明如下：
  • speakerId：说话人唯一标识，用于区分发言者，在助手模式中使用，会拼接在当前语句最前方。
  • final：布尔值，用于标识当前语句是否结束，默认值为 false。

​
5.3 用户消息与机器人消息差异说明

对比项用户消息机器人消息
内容更新方式每包 text 覆盖当前一句（整句识别结果替换）每包 text 拼在当前一句末尾（流式累加）
speakerId非空时拼在句首，便于区分说话人一般无需使用
final == false只刷新当前句，不换行只刷新当前句，不换行
final == true将当前句写入历史并换行，清空当前句将当前句写入历史并换行，清空缓冲

​
5.4 取消事件订阅

为避免内存泄漏和重复回调，建议在页面销毁时取消所有事件订阅，相关方法如下： 
// 取消指定事件的指定监听
fun off(event: ChatEvent, listener: ChatEventListener)

// 取消指定事件的所有监听
fun off(event: ChatEvent)

// 取消 onAny 方法注册的指定监听
fun offAny(listener: ChatEventListener)

// 取消所有事件的所有监听（推荐页面销毁时使用）
fun removeAll()
建议：页面销毁时，先调用 stopVoiceChat() 结束会话，再调用 removeAll() 取消所有监听，确保资源完全释放。

​
六、错误码说明

所有错误均通过 ChatEvent.ERROR 事件下发，事件 data 为 ErrorMessage 对象，包含 code 错误码和 errMsg 错误描述，具体错误码释义如下：
错误码详细描述
3001参数校验错误（如入参为空、格式非法或缺失必要字段）
3002当前设备无可用网络连接
3003SDK 内部网络请求异常（如网络中断、服务端返回非 2xx 状态码）
3004未获取麦克风权限（RECORD_AUDIO）
3005不支持的渠道或运行平台
3006语音引擎初始化异常
3007本端加入 RTC 频道异常
3008本端离开 RTC 频道异常
3009调用 interrupt() 方法时，语音交互尚未建立连接
3010业务指令序列化失败
3011发送指令或业务数据流失败
3012语音引擎未初始化时，调用了 SDK 功能方法
3013麦克风开关状态设置失败
3014SDK 底层未知异常
3015发起语音会话过程中，底层连接异常中断
3016SDK 底层接收 RTC 数据流异常
3017创建业务数据流通道失败
3018本端加入频道后，远端智能体上线超时
3019远端智能体下线且重连超时
3020业务数据流 JSON 解析失败
3021调用流程互斥（如重复发起未完成的语音启动请求）