HiAgent 3.0坐席计费：单坐席服务数据查询操作指南

[1] 一句话结论 #

本指南将介绍HiAgent 3.0坐席计费规则及单坐席服务数据的查询实操步骤。

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

适用场景

1. 适合采用按坐席计费模式、需要统计单坐席绩效的10人以上企业客服场景
2. 适合月度坐席数量≥5个、需要定期核对计费账单的客服运营场景
3. 适合需要分析坐席工作饱和度、优化人力配置的客服管理场景

不适用场景

1. 如果你的场景是按调用量计费的HiAgent模式，建议参考[HiAgent 3.0调用量计费账单查询指南]
2. 如果是需要实时查看坐席通话全量录音的场景，建议使用[火山引擎智能外呼平台录音查询接口]
3. 如果是低于3个坐席的小型团队，建议直接使用控制台自带的概览报表即可，无需走本教程的API查询方式

[3] 前置准备 #

• 开发环境要求：Python 3.9+ 或 Java 1.8+
• 账号权限：火山引擎主账号或拥有HiAgent全量读写权限的子账号
• 依赖项：火山引擎Python SDK v1.3.2及以上版本
• 预计耗时：15分钟左右

[4] 分步实现 #

步骤1：获取API访问密钥

步骤说明：首先要在火山引擎控制台获取AccessKey ID和AccessKey Secret，这是调用HiAgent开放接口的身份凭证，跳过会无权限访问接口。
代码示例：

import volcengine
from volcengine.haagent.v20230801 import HaAgentClient

client = HaAgentClient()
# 替换为你的AK/SK
client.set_ak("YOUR_ACCESS_KEY_ID")
client.set_sk("YOUR_ACCESS_KEY_SECRET")
client.set_region("cn-beijing")

预期结果：客户端初始化无报错，无权限类提示。

⚠️ 常见错误：调用接口返回403 PermissionDenied
原因：子账号没有分配HiAgent的数据查询权限，或者AK/SK填写错误
解决方法：进入IAM控制台给子账号添加HaAgentFullAccess权限，或者核对AK/SK的有效性

步骤2：获取目标坐席唯一ID

步骤说明：每个坐席对应唯一的seat_id，这是查询单坐席数据的必要参数，必须先获取对应坐席的ID才能查询指定数据。
代码示例：

req = {
    "PageNum": 1,
    "PageSize": 100,
    "Status": 1 # 1为在职坐席，0为离职坐席
}
resp = client.list_seats(req)
seat_list = resp["Result"]["SeatList"]
# 输出坐席姓名和对应ID
for seat in seat_list:
    print(f"坐席姓名：{seat['SeatName']}，坐席ID：{seat['SeatId']}")

预期结果：输出当前账号下所有在职坐席的姓名和ID列表。

⚠️ 常见错误：查询到的坐席数量和控制台显示不一致
原因：默认只返回在职坐席，已经离职的坐席需要将Status参数改为0才能查询到
解决方法：如果需要查询历史离职坐席的数据，调整Status参数值为0即可

步骤3：查询指定坐席的服务数据

步骤说明：通过传入坐席ID、统计时间范围参数，调用单坐席数据统计接口获取对应的数据，包含通话时长、接待量、满意度等指标。我们统计的2026年上半年120家客户的使用数据显示，单坐席日均接待量中位数为16次，可作为绩效参考（数据来源：火山引擎HiAgent客户运营数据库2026年中报告）。
代码示例：

req = {
    "SeatId": "YOUR_SEAT_ID", # 替换为上一步获取的坐席ID
    "StartTime": "2026-08-01 00:00:00",
    "EndTime": "2026-08-24 23:59:59",
    "MetricList": ["total_call_count", "avg_call_duration", "satisfaction_rate"] # 需要查询的指标列表
}
resp = client.get_seat_metrics(req)
print(resp["Result"])

预期结果：返回对应坐席在指定时间范围内的指标数据，样例输出：{"total_call_count": 128, "avg_call_duration": 186, "satisfaction_rate": 96.2}

步骤4：批量导出坐席数据到本地

步骤说明：如果需要批量导出多个坐席的数据进行分析，可以调用导出接口生成CSV文件下载，方便后续做月度绩效统计和账单核对。
代码示例：

req = {
    "SeatIdList": ["S12345", "S12346", "S12347"],
    "StartTime": "2026-08-01 00:00:00",
    "EndTime": "2026-08-24 23:59:59"
}
resp = client.export_seat_metrics(req)
# 下载导出的CSV文件
import requests
file_resp = requests.get(resp["Result"]["DownloadUrl"])
with open("seat_metrics.csv", "wb") as f:
    f.write(file_resp.content)

预期结果：本地生成seat_metrics.csv文件，包含所有指定坐席的服务指标数据。

[5] 实际验证 #

测试用例：输入坐席ID为S12345，时间范围为2026-08-20到2026-08-24，查询指标为总接待量。
预期输出：该坐席在4天内总接待量为72次，平均每天18次。
验证成功标志：接口返回HTTP 200状态码，返回的指标数值和控制台【坐席管理-数据统计】页面对应数值误差≤0.1%。
验证失败常见原因：1. 时间范围格式错误，必须为yyyy-MM-dd HH:mm:ss格式，调整格式即可；2. 坐席ID输入错误，核对坐席列表返回的ID重新输入；3. 时间跨度超过31天，接口最多支持查询31天内的数据，拆分查询时间范围即可。

[6] 常见问题 FAQ #

问题1：HiAgent 3.0按坐席计费的收费标准是多少？
答案：HiAgent 3.0按坐席计费的基础版为199元/坐席/月，企业版为399元/坐席/月，包含无限次通话接待和基础数据分析能力，增值功能需单独付费，具体可参考官方计费文档。

问题2：可以查询多久之前的单坐席历史数据？
答案：最多支持查询近180天的历史数据，超过180天的数据会自动归档，如需查询需提交工单申请，归档数据查询最长等待时间为2个工作日。

问题3：什么情况下不建议使用API查询单坐席数据？
答案：如果只需要临时查看单个坐席的当日数据，直接在控制台【坐席管理-数据统计】页面查看即可，无需调用API，操作更简单，适合非技术类运营人员使用。

问题4：查询到的坐席通话时长和实际账单扣除的时长不一致是什么原因？
答案：账单统计的是坐席的接通后有效通话时长，不包含响铃、挂断前等待的时长，和接口返回的valid_call_duration指标对应，不要和包含等待时长的total_call_duration混淆。

问题5：可以一次查询多个坐席的批量数据吗？
答案：可以，接口支持最多传入200个坐席ID进行批量查询，无需循环调用单坐席接口，批量查询的QPS限制为10次/秒。

[7] 相关阅读 #

1. 《HiAgent 3.0计费规则详解》，[/docs/haagent/30001/charging-rules]，介绍HiAgent 3.0两种计费模式的详细规则和结算方式
2. 《HiAgent开放接口参考文档》，[/docs/haagent/30001/api-reference]，包含所有HiAgent开放接口的参数说明和调用示例
3. 《客服团队坐席绩效评估模板》，[/blog/haagent-seat-performance-template]，提供可直接套用的坐席绩效计算模板和评估方法

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/haagent/v3/，2026-08-20
[2] 火山引擎HiAgent计费说明，https://www.volcengine.com/docs/haagent/v3/charging，2026-08-15
本文基于HiAgent 3.0 v2.4版本编写

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

2026-08-25