---
pageClass: semantic-callouts
---
# 通话记录回调数据格式说明
## 回调地址配置
在接收通话记录回调之前，需要先在平台中配置回调地址。
### 配置入口
前往 [接口回调配置页](https://dashboard.avavox.com/agent/api-paas)，或在平台左侧导航栏中依次进入 **空间管理 → 接口回调**，切换到「回调设置」页签。
### 配置步骤
1. 在左侧「回调配置」列表中选择 **通话记录回调**。
2. 开启 **启用** 开关。
3. 在「回调地址」区域填写 **回调 URL**（回调方式固定为 `POST`）。
4. 在「请求 Header」区域按需添加鉴权、签名等自定义请求头，例如用于鉴权的 Token。
5. 点击 **测试连接** 验证地址是否可达。
6. 确认无误后点击 **保存配置**。
> **说明：** 配置保存并启用后，系统会在通话的各个处理阶段向该地址发送 POST 请求，
> 请求体为 JSON 格式，具体字段见下方「字段说明」。
> 同一通通话会触发多次回调，详见下方「回调时机」。
::: warning 两类回调需分别配置
「通话记录回调」和「导入结果回调」是两套彼此独立的配置，各自有独立的地址与开关，**保存时只作用于当前选中的那一项**。若同时需要接收号码导入结果，请另行配置，详见[《导入结果回调数据格式说明》](https://avavox.com/docs/developer/data-import-callback.html)。
:::
## 回调时机
**一通通话结束后，系统可能会针对该通话回调多次**。这是因为振铃音识别、打标签、对话文本转译等处理是异步完成的，每完成一个阶段，系统都会推送一次当前最新的完整通话记录。本次回调由哪个阶段触发，通过 `event` 字段区分：
- `call_hangup`：通话挂断，首次生成通话记录
- `ringtone_recognition`：振铃音识别出结果（例如识别到【通话中（占线）】），通话状态可能随之更新
- `tag_update`：标签分析完成，`callTags`、`resultTags` 等标签字段已产生
- `voice_transcription`：对话内容完成文本转译，`conversationContent` 等字段已产生
同一通通话的多次回调 `sessionId` 相同，且**越靠后的回调数据越完整**。当收到 `lastCallback` 为 `true` 的回调时，表示该通通话的数据已全部就绪，后续不会再有回调。
::: warning 请勿按 sessionId 简单去重
若只需保留一份最终数据，请勿在收到第一次回调后就丢弃后续回调，否则会丢失标签、对话文本等异步产生的数据。建议以 `sessionId` 为主键对本地数据做**覆盖更新**，或以 `lastCallback = true` 的那次回调作为最终数据。
:::
## 字段说明
sessionId string
通话记录 ID，每通通话都有一个唯一的 ID。同一通通话的多次回调，该 ID 保持不变。
---
event string
本次回调的触发事件。一通通话会经历挂断、振铃音识别、打标签、文本转译等多个处理阶段，每个阶段完成时系统都会推送一次回调，该字段用于标识本次回调由哪个阶段触发。枚举值如下：
- `call_hangup`：**通话挂断**。电话挂断后推送，携带通话状态、时长、录音等基础数据。
- `ringtone_recognition`：**振铃音识别完成**。系统识别出振铃音所代表的含义（例如【通话中（占线）】）后推送，通话状态（`callStatus`）可能随识别结果更新。
- `tag_update`：**打标签完成**。通话被成功打上标签后推送，此时 `callTags`、`callTagMap`、`resultTags`、`resultTagMap` 字段已更新。
- `voice_transcription`：**文本转译完成**。对话内容被转译为文本后推送，此时 `conversationContent` 字段已更新。
---
lastCallback boolean
是否为该通通话的最后一次回调。`true` 表示本次回调的数据即为该通通话的最终数据，后续不会再有回调；`false` 表示后续还可能有回调。
---
customerId string
客户 ID，客户的唯一标识。
---
phoneNumber string
客户号码，可以是标准手机号，也可以是固话。
---
numberLocation string
客户号码归属地。
---
numberCarrier string
客户号码所属运营商。
---
callStatus string
通话状态，枚举值如下：
- `unconnected`：未接通
- `call_success`：呼叫成功
- `line_fault`：线路故障
- `no_one_answer`：无人接听
- `timeout`：超时未接听
- `user_refuse`：用户拒接
- `voice_mail`：语音信箱
- `call_remind`：来电提醒
- `unreachable`：无法接通
- `insufficient_balance`：用户欠费
- `powered_off`：关机
- `service_suspended`：停机
- `invalid_number`：空号
- `call_fail`：呼叫失败
- `busy`：占线
- `call_rate_limit`：呼叫限制
---
robotId string
机器人 ID，通话所使用的机器人。
---
robotName string
机器人名称。
---
taskId string
任务 ID，通话所绑定的任务。
---
taskName string
任务名称。
---
lineId string
线路ID。
---
lineName string
线路名称。
---
callAttemptNumber int
呼叫次序，表示同一客户号码在同一任务中的第几次呼叫尝试，从 1 开始计数。当对同一号码进行多次外呼时，该字段用于标识这是第几次拨打。
---
retryCall boolean
是否为重试呼叫（由重呼配置触发的通话标记），`true-是`，`false-否`
---
hangupParty string
挂断方：
- `customer`：客户挂断
- `system`：系统挂断
---
callDuration int
通话时长，单位为秒，当通话状态非正常接通时，通话时长为 `null`
---
ringDuration int
振铃时长，单位：秒
---
turnCount int
对话轮次，通话过程中用户与机器人之间完成的对话总轮次。
---
importedAt string
通话记录被系统导入的时间。示例 `2026-02-09 10:23:45`。
---
callStartTime string
通话开始时间，格式为 `yyyy-MM-dd HH:mm:ss`。
---
callEndTime string
通话结束时间，格式为 `yyyy-MM-dd HH:mm:ss`。
---
callRecording string
通话录音地址，有效期为 7 天，7 天后失效。
---
ringbackToneUrl string
振铃音地址，有效期为7天
---
ext object
随路数据，来源为导入客户时携带的自定义字段，以键值对形式透传。若导入时未携带自定义字段，则为 `null`。
由于同一手机号可能被导入到多个任务或多次导入，不适合作为唯一匹配依据。若需将通话记录关联回您系统中的客户，可在调用[《客户导入》](https://avavox.com/docs/developer/data-import.html)接口时通过 `ext` 传入客户唯一标识（例如 `{"id": "10001"}`），回调时会原样返回，可作为精确匹配依据。
---
callTags array
通话产生的标签（过程标签），可能会有多个标签。
---
callTagMap object
通话产生的标签（过程标签）按标签组归类的映射，与 `callTags` 对应。键为标签组名称，值为该标签组下的标签集合（数组）。
---
resultTags array
通话产生的结果标签，可能会有多个标签。
---
resultTagMap object
通话产生的结果标签按标签组归类的映射，与 `resultTags` 对应。键为标签组名称，值为该标签组下的标签集合（数组）。
---
extractResult object
通话产生信息提取数据。
---
summary string
通话内容摘要。由AI自动分析通话内容生成的简要总结。
前置条件：
需要先启用摘要功能，配置路径：「机器人详情」→「AI智能分析」→「对话摘要设置」
字段说明：
- 包含内容：对话要点、客户意图、关键信息
- 为空情况：未启用配置 / 非有效通话（包含系统标签） / 异步生成中
- 长度限制：最大为500字符
---
conversationContent array
通话内容，以数组格式存储。结构如下：
点击展开字段说明
query string
客户说话内容
---
queryTime string
客户说话时间点，格式为 yyyy-MM-dd HH:mm:ss ，精确到秒
---
answer string
机器人回复内容
---
answerTime string
机器人回复时间点，格式为 yyyy-MM-dd HH:mm:ss，精确到秒
## 返回数据
回调方在成功接收到数据之后，需要返回指定结构的数据。数据结构如下：
success boolean
true ：成功接收到数据，并且数据正常。
::: warning 必须返回响应
请务必在成功处理后返回上述结构，且响应的 `Content-Type` 必须为 `application/json`。若系统未收到符合要求的响应（包括 `Content-Type` 非 `application/json`、返回 `false`、响应超时、非 200 状态码等），将判定本次回调失败并自动重试。
:::
## 数据示例
```json
{
"sessionId": "1234",
"event": "voice_transcription",
"lastCallback": true,
"customerId": "1",
"phoneNumber": "10086",
"numberLocation": "北京",
"numberCarrier": "移动",
"callStatus": "call_success",
"robotId": "12345",
"robotName": "机器人名称",
"taskId": "11",
"taskName": "任务名称",
"lineId": "线路ID",
"lineName": "线路名称",
"callAttemptNumber": 1,
"retryCall": false,
"hangupParty": "customer",
"callDuration": 12,
"ringDuration": 55,
"turnCount": 3,
"importedAt": "2026-02-09 10:23:45",
"callStartTime": "2026-02-09 10:24:00",
"callEndTime": "2026-02-09 10:24:12",
"callRecording": "http://www.aa.com/aaa.wav",
"ringbackToneUrl": "http://www.aa.com/ringing.wav",
"ext": {
"客户姓名": "张三",
"手机尾号": "0086"
},
"callTags": [
"满意",
"很满意"
],
"callTagMap": {
"满意度": [
"满意",
"很满意"
]
},
"resultTags": [
"有需求"
],
"resultTagMap": {
"意向度": [
"有需求"
]
},
"extractResult": {
"满意度调查": "非常满意"
},
"summary": "客户在对话中表现出对客服提及的项目有一定关注，虽未明确表达参与意愿，但回应中包含知道了、嗯嗯嗯等认可性语言，结合上下文判断存在潜在意向。",
"conversationContent": [
{
"query": "WELCOME",
"queryTime": "2026-02-09 10:24:00",
"answer": "你好，我是机器人",
"answerTime": "2026-02-09 10:24:01"
},
{
"query": "你好，我是客户",
"queryTime": "2026-02-09 10:24:05",
"answer": "好的，咱们开始对话吧",
"answerTime": "2026-02-09 10:24:06"
}
]
}
```
## 响应示例
```json
{
"success": true
}
```