本文介绍如何在 App 的 AI 助手页面中,用同一个通话按钮实现两种语音体验:与 AI 实时语音对话,以及转人工后用 CallKit 语音呼叫人工坐席。

用户点击通话按钮后,App 会先向服务端查询当前的人工接入状态:没有转人工时,进入 AI 语音通话;坐席已接入时,直接用 TUICallKit 拨打坐席。这套能力已经内置在 Chat UIKit 的 AI 助手页面中,您只需要把页面接入到 App,并提供助手列表和人工接入状态两项数据。
体验流程
体验 AI 语音通话
1. 进入 AI tab 页,首屏是语音通话入口,单击绿色的点击开始通话按钮。首次使用时,请允许麦克风权限。
2. 进入通话页后,直接说出您的问题。通话页会依次显示三种状态:
正在听...:AI 正在识别您的语音,识别出的文字会实时显示。
思考中...:您说完后,AI 正在根据知识库生成回答。
可继续说话:AI 正在用语音播报回答。此时您可以随时开口打断,重新提问。
3. 单击字幕按钮,可以展开对话文字;单击麦克风按钮可以静音;单击红色按钮结束通话。

4. 挂断后,页面会自动切换到文字会话,您说的话和 AI 的回答都以文字形式保留在聊天记录中。单击左上角的 ‹ 语音,可以回到语音首屏。
说明:
实时语音依赖语音识别能力。如果当前应用的语音识别资源包已用完或未开通,进入通话页时会提示“语音识别不可用”。
Android 端要求系统为 Android 10 及以上,且设备支持 Opus 音频编解码。不满足时,AI tab 页不会显示语音首屏,而是直接进入文字会话。
体验转人工后的语音通话
1. 在 AI tab 页的聊天界面,单击输入框上方的转人工按钮(也可以直接发送“转人工”)。
2. 此时再单击语音通话图标,会提示“正在排队等待人工接入,请稍后再试”。请等待客服坐席接入。
说明:
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 还是人工。import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgentLoaderimport io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatusLoaderimport io.trtc.tuikit.chat.uikit.pages.AIAssistantPageViewval aiPage = AIAssistantPageView(context)aiPage.setup(agentLoader = agentLoader, // 步骤2handoffStatusLoader = 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, // 步骤2handoffStatusLoader: handoffStatusLoader, // 步骤3)
说明:
不传
handoffStatusLoader 时,通话按钮始终进入 AI 语音通话,不会分流到人工坐席。步骤2:提供助手列表
助手列表来自 AI 助手服务的
GET /api/support/v1/agents 接口(无需鉴权)。请求该接口后,将返回的每个助手转换为 AIAssistantAgent:import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgentimport io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantAgentLoaderval agentLoader = AIAssistantAgentLoader { onResult ->// 请求 GET https://<您的服务地址>/api/support/v1/agents,解析 agents 数组val agents = listOf(AIAssistantAgent(id = "customer", // 返回的 idname = "",welcome = "你好,有什么可以帮你?", // 返回的 welcomeimUserId = "@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', // 返回的 idname: '',welcome: '你好,有什么可以帮你?', // 返回的 welcomeimUserId: '@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 的呼叫对象。import io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatusimport io.trtc.tuikit.chat.uikit.components.aiassistant.AIAssistantHandoffStatusLoaderval handoffStatusLoader = AIAssistantHandoffStatusLoader { onResult ->// 请求 POST https://<您的服务地址>/api/im/handoff-status,解析返回结果onResult(AIAssistantHandoffStatus(callable = true, // 返回的 callablestate = "assigned", // 返回的 stateseatImUserId = "@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, // 返回的 callablestate: 'assigned', // 返回的 stateseatImUserId: '@customer_seat#1', // 返回的 seat_im_user_id);// 请求失败、缺少登录凭据时,返回 AIAssistantHandoffStatus.inactive,通话按钮会进入 AI 通话}
页面会根据返回结果自动处理:
callable 为 true 且 seatImUserId 不为空:通过 CallKit 发起语音呼叫,呼叫对象为该坐席。state 为排队等待中:提示“正在排队等待人工接入,请稍后再试”,不发起通话。其他情况:进入 AI 语音通话。
注意:
查询接口需要 UserSig 验证身份,请使用用户登录 IM 时的同一个 UserSig。
查询到可呼叫与真正接通之间,坐席可能恰好结束会话或掉线。呼叫未接通时,CallKit 会给出相应提示。