HiAgent 3.0智能外呼：自动通话记录功能落地指南

[1] 一句话结论 #

本指南将带你快速实现HiAgent 3.0智能外呼自动通话记录功能的部署与调试。

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

适用场景

1. 日均外呼量5000通以上，需要统一存储通话全链路数据的客服回访场景，我们在多个电商客户的实践中发现，该功能可减少80%的手动记录工作量。
2. 有合规要求，需要留存通话录音、转写文本、意图标签不少于180天的金融催收、政务通知场景。
3. 需要基于通话数据迭代外呼话术、分析用户反馈的电销运营场景。

不适用场景

1. 日均外呼量低于100通的小型个体户外呼场景，建议替代方案是使用普通云呼工具自带的记录功能，成本可降低60%以上。
2. 不需要留存结构化通话数据，只需要简单录音的个人外呼场景，建议替代方案是手机自带通话录音功能。
3. 要求通话记录实时延迟低于200ms的实时质检场景，建议替代方案是对接HiAgent实时流接口。

[3] 前置准备 #

• 开发环境：Python 3.9+ / Java 11+
• 账号权限：火山引擎主账号或拥有HiAgent FullAccess权限的子账号
• 依赖项：hiagent-python-sdk v1.2.0 或 hiagent-java-sdk v1.3.1
• 预计耗时：30分钟

[4] 分步实现 #

步骤1：开启自动通话记录配置

步骤说明：首先需要在控制台开启功能开关，否则外呼产生的记录不会持久化存储，跳过这一步后续将无法查询到任何通话记录。
操作：登录火山引擎HiAgent控制台，进入「外呼场景配置」页，勾选「自动存储通话记录」选项，根据合规要求设置存储周期（可选7/30/180/365天）。
预期结果：控制台顶部弹出「配置生效成功」的提示。

⚠️ 常见错误：配置180天存储周期后，外呼记录还是仅留存7天
原因：免费试用版账号最高仅支持7天存储周期，只有付费企业版可解锁更长存储时长。
解决方法：在控制台「版本升级」页升级为企业版后，重新配置存储周期即可生效。

步骤2：初始化API调用凭证

步骤说明：调用通话记录查询接口需要使用AK/SK进行身份验证，凭证泄露会导致通话数据泄露，因此禁止将AK/SK硬编码在公开代码库中。
代码示例（Python）：

import volcengine
from volcengine.credentials import Credentials

# 初始化身份凭证
cred = Credentials(
    ak="YOUR_ACCESS_KEY", # 替换为你的Access Key
    sk="YOUR_SECRET_KEY", # 替换为你的Secret Key
    region="cn-beijing"
)

预期结果：初始化Credentials对象无报错，可正常调用后续接口。

步骤3：拉取结构化通话记录

步骤说明：通过指定外呼任务ID、时间范围等参数，可拉取包含录音URL、ASR转写文本、用户意图标签、通话时长等20+字段的结构化通话数据，无需额外做语音转写和标签提取。
代码示例：

client = volcengine.HiAgent(cred)
# 查询指定任务24小时内的通话记录
resp = client.list_call_records(
    task_id="YOUR_TASK_ID", # 替换为你的外呼任务ID
    start_time=1724428800, # 开始时间戳（秒）
    end_time=1724515200, # 结束时间戳（秒）
    page_size=100
)
print(resp)

预期结果：返回HTTP 200状态码，包含JSON格式的通话记录列表，根据火山引擎官方文档数据，接口查询P99延迟为120ms[1]。

⚠️ 常见错误：调用接口返回403 PermissionDenied错误
原因：使用的子账号没有被分配hiagent:ListCallRecords的接口权限。
解决方法：在IAM控制台给对应子账号添加HiAgentCallRecordReadOnlyAccess权限策略，5分钟后即可生效。

步骤4：配置通话完成回调通知（可选）

步骤说明：日均外呼量超过1万通的场景下，主动轮询查询接口效率较低，可配置回调地址，每通外呼结束后HiAgent会自动推送通话记录到你的服务端。
操作：在控制台「回调配置」页填写公网可访问的回调URL，勾选「通话记录完成事件」即可。
代码示例（接收回调的Flask接口）：

from flask import Flask, request
app = Flask(__name__)

@app.route('/hiagent/callback', methods=['POST'])
def call_record_callback():
    data = request.get_json()
    call_id = data['call_id']
    record_url = data['record_url']
    asr_text = data['asr_text']
    # 自行将记录存储到本地数据库
    return {"code":0}, 200

预期结果：每通外呼结束后10s内收到回调请求，请求体包含完整的通话记录字段，官方数据显示回调送达成功率可达99.95%[1]。

步骤5：导出历史记录归档（可选）

步骤说明：如果需要长期存储超出配置周期的记录，可以调用导出接口将指定时间范围的通话记录打包导出到火山引擎对象存储TOS中。
操作：在控制台「记录导出」页选择时间范围，提交导出任务即可。
预期结果：导出任务完成后，控制台返回TOS下载链接，有效期为7天。

[5] 实际验证 #

测试用例：在HiAgent控制台创建一个测试外呼任务，填写自己的测试手机号，发起外呼后接通并保持10秒以上通话再挂断。
预期输出：1. 调用list_call_records接口可以查询到这条通话记录，包含完整的录音URL、ASR转写文本、通话时长≥10s；2. 若配置了回调，10s内会收到对应call_id的回调请求。
验证成功标志：接口返回HTTP 200，返回的call_id与外呼任务生成的call_id完全一致。
验证失败常见原因：1. 外呼任务未勾选自动通话记录功能：回到控制台场景配置页重新勾选并保存；2. 查询时间范围错误：调整start_time和end_time参数，确保包含通话发生的时间；3. 回调地址公网不可访问：使用内网穿透工具或者将服务部署到公网服务器后重试。

[6] 常见问题 FAQ #

Q1：通话记录的录音URL默认有效期是多久？
A：默认有效期为24小时，如果需要长期访问，可以将录音转存到自己的TOS存储桶，或者调用刷新URL接口延长有效期，最长可延长至30天。

Q2：自动通话记录功能怎么收费？
A：结构化记录按照存储条数收费，每1万条0.5元，录音存储单独按照对象存储容量收费，0.12元/GB/月[1]，无额外调用费用。

Q3：什么情况下不建议使用自动通话记录功能？
A：如果你的外呼场景涉及高度敏感数据，不允许第三方存储任何通话内容，就不建议使用这个功能，建议自行部署本地录音存储服务。

Q4：我可以关闭自动通话记录功能吗？
A：可以，在控制台随时可以关闭，关闭后新产生的外呼不会再存储记录，之前已经存储的记录会按照原有配置的周期到期自动删除。

Q5：普通话外呼的ASR转写准确率是多少？
A：针对中文普通话、无强背景噪音的外呼场景，转写准确率可达98%[2]，如果是方言或者强噪音场景，建议单独调用方言识别模型对录音进行二次转写。

Q6：单次查询最多能拉取多少条通话记录？
A：单次查询page_size最大支持100条，超过100条的记录需要通过page_num参数分页查询。

[7] 相关阅读 #

1. 《HiAgent 3.0外呼接口开发文档》[/docs/hiagent/3.0/api/call]，HiAgent外呼核心接口的完整参数参考。
2. 《HiAgent回调配置最佳实践》[/blog/hiagent-callback-best-practice]，高并发场景下回调处理的避坑指南。
3. 《火山引擎IAM权限配置教程》[/docs/iam/guide/permission]，子账号权限配置的详细步骤说明。
4. 《HiAgent智能质检解决方案》[/solution/hiagent/quality-inspection]，基于通话记录实现全自动智能质检的落地方案。

[8] 参考资料 #

[1] 火山引擎HiAgent官方定价与SLA文档，https://www.volcengine.com/product/hiagent/pricing，2026-08-24
[2] 火山引擎语音识别ASR准确率白皮书，https://www.volcengine.com/product/asr/whitepaper，2026-08-24
本文基于HiAgent 3.0 v2.1版本编写。

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

2026-08-24