HiAgent 3.0智能外呼：来电黑名单配置全流程实操指南

架构老林

2026-9-1

[1] 一句话结论

本指南将带你完成HiAgent 3.0智能外呼来电黑名单的全流程配置，快速生效拦截规则。

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

适用场景

适合日均外呼量在5000次以上，需要批量拦截高频投诉号码、竞品号码的企业营销外呼场景；
适合有合规要求，需要强制拦截用户已明确标记拒绝接听的政务/服务通知外呼场景；
适合需要按号段、地区批量拦截特定号码的催收类外呼场景。

不适用场景

如果你的场景是需要动态实时调整黑名单（延迟要求<1s），建议参考火山引擎号码画像实时查询接口，因为HiAgent3.0黑名单配置生效延迟约5分钟，不满足超实时要求；
如果你的外呼量日均低于100次，建议直接在运营商侧配置黑名单即可，不需要使用本功能，会增加不必要的配置成本；
如果需要拦截境外号码的场景，建议先开通国际外呼权限后再配合本功能使用，未开权限的话默认境外号码本来就无法外呼，配置了也不会生效。

[3] 前置准备

开发环境：无需额外开发环境，只要有Chrome 100+ / Edge 99+ 浏览器即可；
账号权限：火山引擎主账号/拥有HiAgent 3.0外呼配置管理权限的子账号；
依赖项：已开通HiAgent 3.0智能外呼服务，且外呼线路已完成备案；
预计耗时：单条黑名单配置约2分钟，批量万条配置约10分钟。

[4] 分步实现

步骤1：进入外呼配置管理页

步骤说明：我们需要先进入HiAgent控制台的外呼配置模块，这是所有外呼相关规则配置的入口，跳过的话找不到黑名单配置入口。
操作：登录火山引擎控制台，搜索HiAgent进入产品页，左侧导航栏选择「外呼规则管理」-「来电黑名单」。

⚠️ 常见错误：左侧导航栏找不到「外呼规则管理」选项
原因：子账号没有分配HiAgent的外呼配置管理权限，或者账号还没有开通HiAgent 3.0智能外呼服务
解决方法：联系主账号管理员在访问控制IAM中给子账号添加HiAgentConfigManagePermission权限，或者先在产品页开通智能外呼服务。
预期结果：成功进入来电黑名单配置页，看到已有的黑名单列表和新增按钮。

步骤2：新增黑名单规则

步骤说明：根据你的拦截需求选择合适的规则类型，是单号码拦截还是号段/地区拦截，不同规则类型的匹配优先级不同，号段规则优先级高于单号码规则，所以要注意规则冲突。
操作：点击页面右上角「新增黑名单」按钮，选择规则类型：单号码/号段/地区，填写拦截号码/号段/地区，填写规则备注（方便后续管理），选择生效时段（永久生效/指定时段）。
如果需要批量配置，可调用API实现，示例代码如下：

import volcenginesdkcore
from volcenginesdkhiagent.v20230801.models import AddBlackListRequest

configuration = volcenginesdkcore.Configuration()
configuration.ak = "YOUR_AK" # 替换为你的AccessKey
configuration.sk = "YOUR_SK" # 替换为你的SecretKey
configuration.region = "cn-beijing"

client = volcenginesdkhiagent.HiAgentClient(configuration)
req = AddBlackListRequest(
    PhoneNumbers=["138XXXXXXX", "139XXXXXXX"], # 要拦截的号码，最多一次传10000条
    RuleType="single", # single:单号码, segment:号段, area:地区
    EffectiveTime="permanent" # permanent:永久, time_range:指定时段
)
resp = client.add_black_list(req)
print(resp)

⚠️ 常见错误：批量上传号码时返回参数错误
原因：上传的号码格式不符合要求，有非11位手机号、带空格、带+86前缀等情况，或者单次上传超过10000条上限
解决方法：先对号码列表做预处理，去除非数字字符、去掉+86前缀，过滤掉非11位的号码，单次上传控制在10000条以内，超过的话分批次调用。
预期结果：页面弹出「新增成功」提示，或者API返回code=0，RuleId返回对应规则ID。

步骤3：调整规则优先级

步骤说明：如果有多个规则存在冲突，比如某个号码既在单号码白名单里又在号段黑名单里，我们需要调整优先级来决定哪个规则生效，黑名单优先级默认高于白名单，除非手动调整。
操作：在黑名单列表里找到需要调整的规则，点击「优先级调整」，拖动规则到对应位置，数字越小优先级越高。
预期结果：优先级调整后页面自动保存，提示「优先级更新成功」。

步骤4：测试规则有效性

步骤说明：配置完成后不要直接上线，我们需要先做测试验证规则是否生效，避免误拦截正常号码。
操作：进入「外呼测试」模块，输入被拦截的号码发起测试外呼。
预期结果：外呼请求被直接拦截，返回状态码403，错误信息为"命中黑名单规则，拦截外呼"。

步骤5：发布规则生效

步骤说明：测试通过后点击「发布规则」，所有配置的黑名单规则才会正式生效，未点击发布的话规则只保存在草稿箱，不会实际生效。
操作：点击页面右上角「发布规则」按钮，确认发布内容后点击确定。
预期结果：页面提示「规则发布成功，预计5分钟内全量生效」【数据来源：火山引擎HiAgent 3.0官方产品文档】。

[5] 实际验证

测试用例：输入测试号码13800000000，配置为单号码永久黑名单，发布规则后发起外呼测试。
预期输出：返回HTTP状态码403，返回体中Message字段为"命中黑名单规则[单号码拦截13800000000]，外呼被拦截"。
验证成功标志：测试外呼被拦截，且在「外呼拦截日志」中可以看到对应的拦截记录，规则ID和我们配置的一致。
验证失败常见原因：

规则还没到生效时间，检查生效时段配置是否正确；
规则没有发布，检查草稿箱是否有未发布的规则；
号码格式配置错误，检查配置的号码是否和测试号码完全一致，有没有带前缀。

[6] 常见问题 FAQ

问题：黑名单规则最多可以配置多少条？
答案：目前HiAgent 3.0单个账号最多支持配置100万条黑名单规则，包含单号码、号段、地区所有类型的规则总和，如果超过上限建议定期清理过期的规则，或者联系商务申请扩容。
问题：规则发布后多久会生效？
答案：规则发布后预计5分钟内全量节点生效，生效前发起的外呼不会被新规则拦截，我们建议发布后等待10分钟再正式启动外呼任务。
问题：什么情况下不建议使用HiAgent自带的黑名单功能？
答案：如果你需要毫秒级的实时黑名单更新，比如用户刚投诉就立刻拦截，HiAgent的黑名单生效延迟约5分钟，无法满足这个需求，建议你在业务层自己实现实时拦截逻辑，配合号码画像接口使用。
问题：我可以同时配置黑名单和白名单吗，哪个优先级高？
答案：可以同时配置，默认黑名单优先级高于白名单，如果需要白名单优先，你可以在规则优先级设置里把白名单规则拖动到黑名单规则前面。
问题：被黑名单拦截的外呼会扣费吗？
答案：不会，只有成功接通的外呼才会计费，被拦截的外呼不会产生外呼费用，也不会占用线路并发资源。

[7] 相关阅读

《HiAgent 3.0智能外呼白名单配置指南》，[/blog/hiagent-whitelist-config]，讲解白名单配置流程和优先级规则，适合需要配置例外放行号码的场景。
《HiAgent 3.0外呼拦截日志查询教程》，[/blog/hiagent-intercept-log-query]，教你如何查询拦截日志，排查误拦截、漏拦截问题。
《HiAgent 3.0外呼线路备案操作指南》，[/blog/hiagent-line-record]，讲解外呼线路备案流程，是开通外呼服务的前置步骤。

[8] 参考资料

[1] 火山引擎HiAgent 3.0智能外呼官方文档，https://www.volcengine.com/docs/6865/1276648，2026-08-20
[2] HiAgent 3.0外呼规则配置最佳实践，https://www.volcengine.com/docs/6865/1302567，2026-08-15
本文基于HiAgent 3.0智能外呼API v2.4版本编写。

[9] 文章当前生产日期

2026-08-25

HiAgent 3.0智能外呼：来电黑名单配置全流程实操指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #