---
title: 洞察数据接口总览
---

# 洞察数据接口总览

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

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

## 接口清单

| 接口 | 方法 & 路径 |
| --- | --- |
| [洞察列表查询](https://avavox.com/docs/developer/insight/record-query.html) | `POST /open/api/v1/insight/records/query` |
| [洞察详情](https://avavox.com/docs/developer/insight/record-detail.html) | `GET /open/api/v1/insight/records/{insightId}` |
| [通话录音地址](https://avavox.com/docs/developer/insight/record-audio.html) | `GET /open/api/v1/insight/records/{insightId}/audio` |
| [查询筛选字典](https://avavox.com/docs/developer/insight/dicts.html) | `GET /open/api/v1/insight/dicts` |

## 鉴权

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

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

App Key 的创建与管理详见 [《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。

本组接口**不接受任何空间参数**，无需传入空间 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` 当作不合格处理。

## 分页

[洞察列表查询](https://avavox.com/docs/developer/insight/record-query.html)使用 `pageNo` / `pageSize` 分页：

| 参数 | 默认 | 取值范围 |
| --- | --- | --- |
| `pageNo` | `1` | ≥ 1 |
| `pageSize` | `10` | 1 ~ 100 |

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

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

## 枚举定义

### insightResult 洞察结果

| 值 | 含义 |
| --- | --- |
| `PASS` | 合格 |
| `FAIL` | 不合格 |

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

### insightStatus 洞察状态

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

### level 条目严重程度

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

### role 说话人角色

| 值 | 含义 |
| --- | --- |
| `ROBOT` | AI 机器人 |
| `CUSTOMER` | 客户 |

## 对接须知

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

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

[洞察列表查询](https://avavox.com/docs/developer/insight/record-query.html)的 `insightTimeRange` 筛选的是**洞察分析时间**：一通 4 月 1 日的电话若在 4 月 2 日才完成分析，会落在 4 月 2 日的窗口里。响应中的 `callStartTime` 仍是通话开始时间，两者可能不在同一天。

::: warning 分页期间数据可能变化
洞察分析时间在记录创建时写入、分析完成时更新。若某条记录在你翻页过程中完成分析，其时间会前移，可能导致后续页少返回记录。对完整性有要求的场景，建议按较短窗口分段拉取，并以 `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 分钟，**需在用户点击播放时实时获取**，不要提前批量拉取。

## 相关文档

- [App Key 创建与管理](https://avavox.com/docs/developer/app-key.html)