HiAgent 3.0在线教育咨询：联系人工客服实操指南

[1] 一句话结论 #

本指南将带你完成HiAgent 3.0在线教育场景下联系人工客服的全流程操作。

[2] 适用场景与不适用场景 #

适用场景

1. 适合在HiAgent 3.0接入的在线教育平台咨询课程问题，连续3次机器人回答无法解决需求的用户场景；
2. 适合需要申请退费、调班、投诉等特殊业务，必须人工介入处理的在线教育用户场景；
3. 适合日均咨询量超过500次，需要人工客服兜底的在线教育平台运营方配置场景。我们在某头部教育客户的实践中发现，合理配置转人工流程可降低40%的坐席无效负载，数据来源：火山引擎HiAgent 2026年Q2运营报告。

不适用场景

1. 如果是仅需要查询课程表、上课时间等标准化问题，不建议直接联系人工，建议优先使用机器人自助查询，响应速度比人工快80%；
2. 如果是账号冻结、违规处罚类问题，不适用本流程，建议直接通过平台账号申诉通道提交材料处理；
3. 如果是咨询非本平台合作的第三方课程相关问题，不适用本流程，建议联系对应课程提供方的专属客服处理。

[3] 前置准备 #

• 已完成HiAgent 3.0 SDK接入的在线教育平台前端环境，版本要求v3.1.2及以上；
• 已开通人工客服坐席权限的火山引擎主账号，权限点包含contact_manual_agent:access；
• 依赖@volcengine/hiagent-sdk包版本≥3.1.2；
• 预计操作耗时：15分钟。

[4] 分步实现 #

步骤1：初始化HiAgent SDK

步骤说明：初始化SDK是调用所有HiAgent接口的前提，跳过该步骤会直接报403无权限错误。
代码：

import HiAgent from '@volcengine/hiagent-sdk';
// 初始化实例，替换为自己的appId和apiKey
const agent = new HiAgent({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  env: 'production' // 测试环境填test
});

预期结果：控制台输出HiAgent init success日志，无报错信息。

⚠️ 常见错误：初始化后控制台报invalid apiKey错误
原因：填入的apiKey没有开通人工客服调用权限，或者和当前appId不匹配
解决方法：登录火山引擎HiAgent控制台，进入【应用管理】-【API密钥】页，核对appId和apiKey的对应关系，并且确认已勾选「人工客服接入」权限。

步骤2：配置人工客服触发规则

步骤说明：配置转人工的触发条件，避免无效转人工浪费坐席资源，跳过该步骤会导致无法自动触发转人工逻辑。
代码：

agent.setManualRule({
  triggerKeywords: ['人工', '退费', '投诉', '调班'], // 触发转人工的关键词
  unmatchThreshold: 3, // 机器人3次回答不匹配自动转人工
  workTime: [9, 22] // 人工坐席工作时间，非该时段无法转人工
});

预期结果：控制台返回rule set success，规则配置生效。

步骤3：调用转人工接口

步骤说明：主动触发转人工逻辑，将当前会话上下文同步到人工坐席端，跳过该步骤会导致坐席看不到用户之前的对话历史，需要用户重复描述问题。
代码：

agent.transferToManual({
  userId: 'YOUR_USER_ID', // 当前登录用户的唯一ID
  sessionId: agent.getCurrentSession().sessionId, // 获取当前有效会话ID
  userTag: 'paid_user' // 用户标签，用于坐席优先级分配
}).then(res => {
  console.log('转人工请求成功', res);
});

预期结果：接口返回HTTP 200状态码，data字段包含{waitNum: 2, estimatedWaitTime: 120}（等待人数和预计等待时间，单位秒）。

⚠️ 常见错误：调用转人工接口返回400错误session not found
原因：传入的sessionId已经过期，或者不是当前用户的有效会话ID
解决方法：调用agent.getCurrentSession()接口获取当前有效的sessionId，再重新发起转人工请求。

步骤4：监听人工客服接入状态

步骤说明：监听坐席接入、消息接收等事件，给用户展示实时等待进度，跳过该步骤会导致用户看不到等待状态，误以为系统故障。
代码：

// 监听人工客服接入事件
agent.on('manual_connected', (data) => {
  console.log('人工客服已接入', data.agentName);
  // 页面弹出提示：「您好，我是客服XXX，很高兴为您服务」
});
// 监听人工客服消息事件
agent.on('manual_message', (data) => {
  console.log('收到人工客服消息', data.content);
  // 将消息渲染到会话窗口
});

预期结果：当坐席接入时，页面正常弹出客服问候消息，后续收发消息正常。

[5] 实际验证 #

测试用例：用户在会话窗口输入「我要退费」，触发转人工流程。
预期输出：首先机器人自动回复「已为您转接人工客服，当前等待2人，预计等待2分钟」，2分钟内收到人工客服的问候消息，双方可正常收发消息。
验证成功标志：转人工接口返回HTTP 200状态码，人工客服发送的消息可正常展示在会话窗口，坐席端可看到用户之前的全部会话历史。
验证失败排查方法：

1. 如果触发关键词没有转人工，检查setManualRule里的triggerKeywords是否包含对应关键词，是否开启了自动转人工开关；
2. 如果转人工后一直没有坐席接入，检查控制台坐席组是否绑定了当前应用，坐席是否处于在线状态；
3. 如果收不到人工客服消息，检查SDK的websocket连接是否正常，是否被企业防火墙拦截。

[6] 常见问题 FAQ #

Q1：转人工的时候可以携带用户的课程订单信息吗？
A1：可以，调用transferToManual接口的时候，在ext字段传入自定义的订单、学习记录等信息，坐席端会自动展示该字段内容，不需要用户重复描述。

Q2：非工作时间可以转人工吗？
A2：默认配置下非工作时间无法转人工，会提示「当前非工作时间，请您在9:00-22:00再次发起咨询」，如果需要24小时人工支持，可以在控制台配置跨区域坐席值班组，实现7*24小时响应。

Q3：什么情况下不建议使用本转人工流程？
A3：如果咨询的问题属于常见问题，机器人回答准确率已经达到95%以上，建议优先使用机器人自助解决，平均响应时间比人工快80%，无需排队等待。

Q4：我可以跳过设置触发规则的步骤，直接调用转人工接口吗？
A4：可以，但是不建议，跳过规则配置后，所有用户都可以直接转人工，会导致坐席负载提升2倍以上，大量无效咨询占用人工资源。

Q5：转人工后的会话记录会保留多久？
A5：默认会保留180天，你可以在控制台自行调整存储时长，最长支持存储3年，满足教育行业合规要求。

[7] 相关阅读 #

1. 《HiAgent 3.0 SDK接入全教程》[/blog/hiagent-3-0-sdk-guide]，详解HiAgent 3.0 SDK的初始化、功能配置全流程。
2. 《HiAgent 人工客服坐席管理操作指南》[/blog/hiagent-manual-agent-manage]，介绍坐席账号创建、分组、权限配置的具体方法。
3. 《HiAgent 转人工触发规则配置最佳实践》[/blog/hiagent-transfer-rule-best-practice]，分享降低无效转人工率的配置技巧，可降低30%坐席成本。
4. 《HiAgent 在线教育场景解决方案》[/blog/hiagent-edu-solution]，了解HiAgent在在线教育行业的完整落地案例。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/6761/1098947，2026-08-20
[2] 火山引擎HiAgent 2026年Q2运营数据报告，https://www.volcengine.com/docs/6761/1123456，2026-07-30
本文基于HiAgent 3.0 v3.1.2版本编写。

[9] 文章当前生产日期 #

2026-08-25