帮你快速理解、总结文档立即下载

单聊 + AI 语音

最近更新时间:2026-11-12 11:09:19
我的收藏
本文介绍如何在 App 的 AI 助手页面中,用同一个通话按钮实现两种语音体验:与 AI 实时语音对话,以及转人工后用 CallKit 语音呼叫人工坐席。

用户点击通话按钮后,App 会先向服务端查询当前的人工接入状态:没有转人工时,进入 AI 语音通话;坐席已接入时,直接用 TUICallKit 拨打坐席。这套能力已经内置在 Chat UIKit 的 AI 助手页面中,您只需要把页面接入到 App,并提供助手列表和人工接入状态两项数据。


体验流程

开始前,请先完成 单聊 + AI 对话,创建好 AI 助手并在 Demo 中添加。下面的步骤以 Demo 的 AI 页为例。

体验 AI 语音通话

1. 进入 AI tab 页,首屏是语音通话入口,单击绿色的点击开始通话按钮。首次使用时,请允许麦克风权限。
2. 进入通话页后,直接说出您的问题。通话页会依次显示三种状态:
正在听...:AI 正在识别您的语音,识别出的文字会实时显示。
思考中...:您说完后,AI 正在根据知识库生成回答。
可继续说话:AI 正在用语音播报回答。此时您可以随时开口打断,重新提问。
3. 单击字幕按钮,可以展开对话文字;单击麦克风按钮可以静音;单击红色按钮结束通话。

4. 挂断后,页面会自动切换到文字会话,您说的话和 AI 的回答都以文字形式保留在聊天记录中。单击左上角的 ‹ 语音,可以回到语音首屏。
说明:
实时语音依赖语音识别能力。如果当前应用的语音识别资源包已用完或未开通,进入通话页时会提示“语音识别不可用”。
Android 端要求系统为 Android 10 及以上,且设备支持 Opus 音频编解码。不满足时,AI tab 页不会显示语音首屏,而是直接进入文字会话。

体验转人工后的语音通话

1. 在 AI tab 页的聊天界面,单击输入框上方的转人工按钮(也可以直接发送“转人工”)。
2. 此时再单击语音通话图标,会提示“正在排队等待人工接入,请稍后再试”。请等待客服坐席接入。
说明:
转人工需要先创建客服坐席并登录坐席工作台,详见 单聊 + AI 对话 的“体验转人工”。
3. 坐席在工作台接入会话后,聊天界面会提示“客服已接入,正在为您服务”。这时再单击语音通话图标,不再进入 AI 通话,而是通过 CallKit 直接语音呼叫该坐席。

4. 坐席在工作台接听后,即可开始人工语音通话。会话结束后,再次单击语音通话图标,会恢复为 AI 语音通话。

接入 UIKit 的 AI 页面

前提条件

已按各平台“全功能接入”文档集成 Chat UIKit,并完成用户登录。
已部署知识库 AI 助手服务,参见 单聊 + AI 对话。
如需转人工后语音呼叫坐席,需先 开通音视频通话服务,并已集成 TUICallKit、完成其登录初始化(参见各平台“全功能接入”中的“音视频通话”)。
语音通话需要麦克风权限。Android 端 UIKit 已声明 RECORD_AUDIO 权限,首次通话时会自动弹出授权;iOS 端(含 Flutter 的 iOS 工程)需在 Info.plist 中添加 NSMicrophoneUsageDescription。

步骤1:引入 AI 助手页面

AI 助手页面由 UIKit 提供,包含助手标题、聊天界面、转人工按钮和通话按钮,您只需要提供两项数据:
助手列表(agentLoader):告诉页面和哪个 AI 助手聊天。
人工接入状态(handoffStatusLoader):告诉页面点击通话按钮时该打给 AI 还是人工。
Android(View)
Flutter
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgentLoader
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatusLoader
import io.trtc.tuikit.chat.uikit.pages.AIAssistantPageView

val aiPage = AIAssistantPageView(context)
aiPage.setup(
agentLoader = agentLoader, // 步骤2
handoffStatusLoader = handoffStatusLoader // 步骤3
)
// 作为普通 View 添加到您的页面或 Tab 中
container.addView(aiPage)
页面所在的 Tab 重新显示时,调用 aiPage.onPageVisible() 刷新助手列表。
import 'package:tencent_chat_uikit/tencent_chat_uikit.dart';

// visible 表示 AI 页面当前是否可见,页面变为可见时会重新获取助手列表
final ValueNotifier<bool> aiTabVisible = ValueNotifier(true);

AIAssistantPage(
visible: aiTabVisible,
agentLoader: agentLoader, // 步骤2
handoffStatusLoader: handoffStatusLoader, // 步骤3
)
说明:
不传 handoffStatusLoader 时,通话按钮始终进入 AI 语音通话,不会分流到人工坐席。

步骤2:提供助手列表

助手列表来自 AI 助手服务的 GET /api/support/v1/agents 接口(无需鉴权)。请求该接口后,将返回的每个助手转换为 AIAssistantAgent:
Android(View)
Flutter
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgent
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgentLoader

val agentLoader = AIAssistantAgentLoader { onResult ->
// 请求 GET https://<您的服务地址>/api/support/v1/agents,解析 agents 数组
val agents = listOf(
AIAssistantAgent(
id = "customer", // 返回的 id
name = "",
welcome = "你好,有什么可以帮你?", // 返回的 welcome
imUserId = "@RBT#AIAssistant", // 返回的 im_user_id,单聊对象
imNickname = "AI 助手" // 返回的 im_nickname,页面标题
)
)
// 回调必须在主线程;请求失败时回传空列表
onResult(agents)
}
Future<List<AIAssistantAgent>> agentLoader() async {
// 请求 GET https://<您的服务地址>/api/support/v1/agents,解析 agents 数组
return [
AIAssistantAgent(
id: 'customer', // 返回的 id
name: '',
welcome: '你好,有什么可以帮你?', // 返回的 welcome
imUserId: '@RBT#AIAssistant', // 返回的 im_user_id,单聊对象
imNickname: 'AI 助手', // 返回的 im_nickname,页面标题
),
];
}

步骤3:提供人工接入状态

通话按钮的分流依赖这一步。请在用户点击通话按钮时,调用 AI 助手服务的 POST /api/im/handoff-status 接口,用当前登录用户的 UserID 和 UserSig 查询转人工进度。
接口返回三个字段,将它们转换为 AIAssistantHandoffStatus:
callable:是否可以呼叫坐席。仅当坐席已接入时为 true。
state:转人工状态。queued / offered 表示排队等待,assigned 表示坐席已接入,closed 或空表示没有进行中的转人工。
seat_im_user_id:已接入的坐席 IM 账号,用作 CallKit 的呼叫对象。
Android(View)
Flutter
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatus
import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatusLoader

val handoffStatusLoader = AIAssistantHandoffStatusLoader { onResult ->
// 请求 POST https://<您的服务地址>/api/im/handoff-status,解析返回结果
onResult(
AIAssistantHandoffStatus(
callable = true, // 返回的 callable
state = "assigned", // 返回的 state
seatImUserId = "@customer_seat#1" // 返回的 seat_im_user_id
)
)
// 请求失败、缺少登录凭据时,回传 AIAssistantHandoffStatus.INACTIVE,通话按钮会进入 AI 通话
}
Future<AIAssistantHandoffStatus> handoffStatusLoader() async {
// 请求 POST https://<您的服务地址>/api/im/handoff-status,解析返回结果
return const AIAssistantHandoffStatus(
callable: true, // 返回的 callable
state: 'assigned', // 返回的 state
seatImUserId: '@customer_seat#1', // 返回的 seat_im_user_id
);
// 请求失败、缺少登录凭据时,返回 AIAssistantHandoffStatus.inactive,通话按钮会进入 AI 通话
}
页面会根据返回结果自动处理:
callable 为 true 且 seatImUserId 不为空:通过 CallKit 发起语音呼叫,呼叫对象为该坐席。
state 为排队等待中:提示“正在排队等待人工接入,请稍后再试”,不发起通话。
其他情况:进入 AI 语音通话。
注意:
查询接口需要 UserSig 验证身份,请使用用户登录 IM 时的同一个 UserSig。
查询到可呼叫与真正接通之间,坐席可能恰好结束会话或掉线。呼叫未接通时,CallKit 会给出相应提示。