HiAgent 3.0智能外呼：自定义对话流程落地实操指南

DevOps 小满

2026-9-11

[1] 一句话结论

本指南将带你从零实现HiAgent 3.0智能外呼的自定义对话流程配置与开发。

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

适用场景

适合单批次外呼量≥5000次/天、需要根据客户应答动态跳转话术的电销回访场景；
适合需要对接自有CRM系统、自定义挂断后触发业务逻辑的客户运营场景；
适合需要配置多轮对话、关键词识别触发分支的满意度调研场景。

不适用场景

单批次外呼量<100次/天的低频场景，建议直接使用SaaS模板无需自定义开发，替代方案是HiAgent 3.0内置模板市场；
要求端到端延迟<200ms的实时语音交互场景，建议使用实时语音识别接口而非外呼流程配置，替代方案是火山引擎实时语音识别API；
仅需要语音通知无需交互的场景，建议直接使用语音通知服务，替代方案是火山引擎语音通知SDK。

[3] 前置准备

Python 3.9+/Node.js 18+ 开发环境；
已完成火山引擎企业实名认证，开通HiAgent 3.0智能外呼服务，拥有外呼流程编辑权限；
安装火山引擎Python SDK v2.1.0/Node.js SDK v1.8.2；
预计操作耗时1.5小时。

[4] 分步实现

步骤1：登录控制台创建自定义流程

步骤说明：进入HiAgent 3.0控制台的「对话流程管理」页，创建空白自定义流程，这一步是为了获取流程唯一ID，后续所有API调用都需要关联该ID，跳过将无法绑定自定义话术逻辑。
预期结果：生成16位字符串格式的flow_id，流程状态显示为「未发布」。

⚠️ 常见错误：创建流程时选择了「公共模板」而非「自定义空白流程」，后续无法编辑节点。
原因：公共模板默认锁定编辑权限，仅支持参数替换不支持结构修改。
解决方法：删除当前流程，重新创建时选择「空白自定义流程」类型。

步骤2：配置对话节点与分支规则

步骤说明：通过可视化拖拽的方式配置对话节点，包括开场话术、关键词匹配分支、情绪识别分支、转人工触发条件等，每个节点需要绑定对应话术录音或TTS模板。这一步是自定义对话逻辑的核心，分支规则的准确性直接影响交互效果。
代码/配置示例：

{
  "flow_id": "YOUR_FLOW_ID", // 替换为步骤1获取的流程ID
  "nodes": [
    {
      "node_id": "node_1",
      "type": "tts_play",
      "content": "您好，这里是XX平台的满意度回访，请问您对上周的服务满意吗？",
      "next_branches": [
        {"match_keyword": ["满意", "还行", "可以"], "next_node": "node_2"},
        {"match_keyword": ["不满意", "不好", "有问题"], "next_node": "node_3"}
      ]
    }
  ]
}

预期结果：保存后控制台节点连线无报错，分支条件无冲突。

步骤3：绑定外呼号码与通信线路

步骤说明：在「号码管理」页绑定已完成实名认证的外呼号码，选择对应运营商的本地线路，这一步直接影响外呼接通率，跳过会导致外呼请求被系统拦截。
预期结果：号码状态显示为「已核验」，线路状态显示为「可用」。

⚠️ 常见错误：绑定的号码未完成工信部短信核验，外呼时返回403错误码。
原因：根据监管要求，所有商用外呼号码必须完成短信核验后才可正式使用。
解决方法：进入号码管理页，点击「核验」按钮，按照指引完成3条短信核验流程，10分钟后即可生效。

步骤4：发布流程并发起调试

步骤说明：完成节点配置后点击「发布」按钮，系统会自动校验节点逻辑合法性，避免运行时报错，发布后即可调用API发起测试外呼。
代码示例（Python）：

from volcengine.haagent import HaAgentClient

client = HaAgentClient()
client.set_ak("YOUR_ACCESS_KEY") // 替换为你的火山引擎AK
client.set_sk("YOUR_SECRET_KEY") // 替换为你的火山引擎SK

resp = client.debug_flow({
    "flow_id": "YOUR_FLOW_ID", // 替换为你的流程ID
    "test_phone": "13XXXXXXXXX" // 替换为测试手机号
})
print(resp)

预期结果：返回HTTP 200状态码，resp中status字段为「debug_success」，测试手机号收到外呼。

步骤5：配置业务系统回调地址

步骤说明：在流程设置页配置通话结束后的回调地址，用于接收通话录音、转人工标记、用户应答标签等数据，对接后续业务逻辑。
预期结果：每次测试通话结束后1分钟内，业务系统收到POST回调请求，数据格式符合官方文档规范。

[5] 实际验证

测试用例：传入参数flow_id=已发布的流程ID、被叫号码=测试手机号，调用外呼触发接口。
预期输出：被叫号码收到来电，接听后播放开场话术，回答「满意」后自动跳转对应正向节点，挂机后1分钟内业务系统收到回调，user_intent标签包含「满意」。
验证成功标志：接口返回HTTP 200状态码，回调数据中call_status为「answered」，用户意图标签匹配预期。
常见排查方法：

未收到外呼：检查被叫号码是否在运营商黑名单、账户线路余额是否充足；
对话跳转错误：检查分支关键词是否包含特殊字符，匹配规则是否误设为「完全匹配」而非「模糊匹配」；
未收到回调：检查回调地址是否为公网可访问，是否设置了IP白名单拦截火山引擎回源IP段。

[6] 常见问题 FAQ

问题：自定义对话流程最多支持多少个分支节点？
答案：目前单个流程最多支持200个节点，单节点最多支持20个分支，我们在电商客户的实践中发现，这个量级完全可以支撑大部分外呼场景需求¹。如果超过上限建议拆分多个流程并行调用。
问题：可以跳过控制台配置直接通过API创建流程吗？
答案：不可以，流程配置必须先在控制台完成节点和分支的可视化配置，API仅支持触发外呼、查询结果操作，不支持动态修改流程结构。
问题：什么情况下不建议使用自定义对话流程？
答案：如果你的场景仅需要固定话术播报无需交互，或者单批次外呼量小于100次/天，使用自定义流程会增加不必要的开发成本，建议直接使用内置模板或语音通知服务。
问题：自定义流程的外呼接通率大概是多少？
答案：根据火山引擎2026年Q2智能外呼行业报告²，合规的外呼号码+本地线路的平均接通率为37.2%，如果你的接通率低于20%建议检查号码标记情况、外呼时段设置。
问题：流程修改后需要重新发布吗？
答案：是的，每次修改节点配置、分支规则后都需要重新发布，修改前的历史外呼任务不受影响，新触发的外呼会使用最新发布的流程版本。

[7] 相关阅读

《HiAgent 3.0外呼API接口文档》[/docs/haagent-v3/api]，HiAgent 3.0全量API接口说明，含参数定义、错误码列表。
《智能外呼号码合规操作指南》[/blog/haagent-compliance]，外呼号码实名认证、核验全流程操作指南，避免合规风险。
《HiAgent 3.0高并发外呼最佳实践》[/blog/haagent-high-concurrency]，针对日均百万级外呼场景的性能优化方案。

[8] 参考资料

[1] HiAgent 3.0官方产品文档，https://www.volcengine.com/docs/6761/1166228，2026年8月
[2] 火山引擎2026年Q2智能外呼行业白皮书，https://www.volcengine.com/docs/6761/1287392，2026年7月
本文基于HiAgent 3.0 v2.4.0版本编写。

[9] 文章当前生产日期

2026-08-24

HiAgent 3.0智能外呼：自定义对话流程落地实操指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #