切换主题

洞察数据接口总览 ​

洞察数据接口用于以编程方式查询 AVAVOX 的通话质检洞察结果，覆盖 列表筛选、洞察详情、通话录音、筛选字典 四个场景，可用于对接自有质检看板、抽检工单系统或数据仓库。

所有洞察接口均为只读查询，不会产生任何副作用。

接口清单 ​

接口方法 & 路径
洞察列表查询POST /open/api/v1/insight/records/query
洞察详情GET /open/api/v1/insight/records/{insightId}
通话录音地址GET /open/api/v1/insight/records/{insightId}/audio
查询筛选字典GET /open/api/v1/insight/dicts

鉴权 ​

洞察接口与其他开放接口使用同一套 App Key，请求头携带：

shell
Authorization: Bearer <App Key>
Content-Type: application/json

App Key 的创建与管理详见 《App Key 创建与管理》。

本组接口不接受任何空间参数，无需传入空间 ID。

统一响应结构 ​

json
{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {}
}

code 为 200 且 success 为 true 表示成功；失败时 data 为 null，message 会指明具体原因。

数据类型约定 ​

  • 请求体与响应体均为 Content-Type: application/json; charset=utf-8，字段统一使用小驼峰命名。
  • 时间：yyyy-MM-dd HH:mm:ss，时区固定 GMT+8，如 2026-04-28 11:35:13。
  • 时长：统一为秒（整数）。
  • 未分析完成的字段返回 null，不是 0 或 FAIL，请勿把 null 当作不合格处理。

分页 ​

洞察列表查询使用 pageNo / pageSize 分页：

参数默认取值范围
pageNo1≥ 1
pageSize101 ~ 100

分页深度上限

硬性限制 pageNo * pageSize <= 10000，超出请求会失败，增大 pageNo 无法突破该上限。需要遍历更多数据时，请收窄 insightTimeRange 分段拉取。

排序固定为洞察分析时间倒序，不开放排序参数。

枚举定义 ​

insightResult 洞察结果 ​

值含义
PASS合格
FAIL不合格

未分析完成时该字段为 null，不是 FAIL。

insightStatus 洞察状态 ​

值含义
PENDING待分析
ANALYZING分析中
ANALYZED已分析
FAILED分析失败

level 条目严重程度 ​

值含义排序权重
VETO一票否决3
SEVERE严重2
MINOR轻微1

role 说话人角色 ​

值含义
ROBOTAI 机器人
CUSTOMER客户

对接须知 ​

以下几点会直接影响取数逻辑，建议在编码前逐条确认。

时间筛选的是洞察分析时间，不是通话时间 ​

洞察列表查询的 insightTimeRange 筛选的是洞察分析时间：一通 4 月 1 日的电话若在 4 月 2 日才完成分析，会落在 4 月 2 日的窗口里。响应中的 callStartTime 仍是通话开始时间，两者可能不在同一天。

分页期间数据可能变化

洞察分析时间在记录创建时写入、分析完成时更新。若某条记录在你翻页过程中完成分析，其时间会前移，可能导致后续页少返回记录。对完整性有要求的场景，建议按较短窗口分段拉取，并以 insightId 去重。

按业务日期对账时，请以响应中的 callStartTime 为准做二次归集。

keyword 为精确匹配 ​

keyword 不支持前缀或子串检索，传入值需与通话记录 ID 或客户号码完整相等。

手机号一律脱敏返回 ​

customerNumber 一律返回脱敏值 183****6716（保留前 3 后 4），固话按区号规则脱敏。当前不提供返回明文的开关。

keyword 仍按明文检索：即使响应脱敏，查询时也请传完整号码。

典型调用链路 ​

1. GET  /open/api/v1/insight/dicts                      拉取规则组 / 失分项 / 机器人 / 标签，初始化筛选项
2. POST /open/api/v1/insight/records/query              按条件分页拉取洞察列表 + 合格/不合格统计
3. GET  /open/api/v1/insight/records/{insightId}        对关注的记录查看评分与诊断详情
4. GET  /open/api/v1/insight/records/{insightId}/audio  需要听原声时换取临时播放地址

字典数据变更低频，可整体缓存；录音地址有效期仅 15 分钟，需在用户点击播放时实时获取，不要提前批量拉取。

相关文档 ​