语音机器人事件推送

语音机器人平台通过 HTTP 回调，将通话结果主动推送至客户业务系统。本接口支持以下三类事件：

事件类型	说明	推送时机
CALL_RECORD	通话记录事件	通话结束或机器人成功转接人工时
CALL_INTENTION	通话意向事件	通话意向及标签分析完成后
CALL_TRANSCRIPT	通话文本事件	通话文本完成持久化后

三类事件均可通过 data.callId 关联同一次通话。

客户需提供可被平台访问的 HTTP 或 HTTPS 回调地址。平台使用以下方式调用该地址：

POST {客户回调地址}
Content-Type: application/json; charset=UTF-8

建议客户回调服务满足以下要求：

支持 POST 请求并接收 JSON 请求体。

在 10 秒内完成响应。

使用 eventId 进行幂等处理，避免重复写入业务数据。

先保存事件，再异步处理耗时业务，避免回调超时。

回调地址应保持稳定；如需变更，请提前通知平台对接人员。

三类事件使用相同的外层结构，具体业务字段位于 data 中。

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "CALL_RECORD",
  "eventTime": "2026-08-10 15:30:45",
  "data": {}
}

字段	类型	必填	说明
eventId	string	是	事件唯一标识，标准 UUID。同一事件重试时该值不变。
eventType	string	是	事件类型，取值见第 1 节。
eventTime	string	是	事件时间，格式为 yyyy-MM-dd HH:mm:ss。
data	object	是	事件业务数据，不同事件类型对应不同结构。

说明：

文档中的 ID 均为 JSON 字符串，客户系统不应按数字类型解析。

时间字符串按平台部署时区解释，联调时由双方确认具体时区。

可选字段无值时可能为 null。

平台可能因网络超时等原因重复推送同一事件，重复事件具有相同的 eventId。

事件类型：CALL_RECORD

推送字段说明

字段	类型	必定推送	说明
callId	string	是	通话唯一标识，用于关联三类事件。
callType	string	否	通话类型业务编码，例如呼入或呼出。
customerNumber	string	否	客户号码。
displayNumber	string	否	外显号码。
serviceNumber	string/null	否	服务号码。
voiceAgentId	string/null	否	语音机器人 ID。
voiceAgentName	string/null	否	语音机器人名称。
callStatus	string	否	通话状态业务编码； ANSWER：已接通，NO_ANSWER：未接通
failureReason	string/null	条件必传	未接通时为失败原因编码；无法识别时为 UNKNOWN，接通时为 null。
hangupParty	string/null	否	挂机方业务编码；CUSTOMER：客户，ROBOT：机器人
startTime	string/null	否	通话开始时间，格式为 yyyy-MM-dd HH:mm:ss。
answerTime	string/null	否	通话接通时间；未接通时为 null。
endTime	string/null	否	通话结束时间，格式为 yyyy-MM-dd HH:mm:ss。
durationSeconds	integer/null	否	通话时长，单位为秒。
transferredToAgent	boolean	是	是否转接人工。
transferType	string/null	否	转人工类型业务编码。
transferTime	string/null	否	转人工时间；未转人工时为 null。
agentNumber	string/null	否	接听坐席号码。
queueNumber	string/null	否	转接队列号码。
recordUrl	string/null	否	通话录音访问地址。
taskId	string	是	关联任务id
dialCount	string	是	该条呼叫数据在任务中的呼叫次数

推送示例

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "CALL_RECORD",
  "eventTime": "2026-08-10 15:30:45",
  "data": {
    "callId": "1054561235365715968",
    "callType": "OUTBOUND",
    "customerNumber": "18780969628",
    "displayNumber": "02867934459",
    "serviceNumber": null,
    "voiceAgentId": "2034500000000000001",
    "voiceAgentName": "售后回访机器人",
    "callStatus": "ANSWER",
    "failureReason": null,
    "hangupParty": "CUSTOMER",
    "startTime": "2026-08-10 15:28:00",
    "answerTime": "2026-08-10 15:28:08",
    "endTime": "2026-08-10 15:30:45",
    "durationSeconds": 157,
    "transferredToAgent": false,
    "transferType": null,
    "transferTime": null,
    "agentNumber": null,
    "queueNumber": null,
    "recordUrl": "https://storage.example.com/record/xxx.wav"
  }
}

转人工场景的相关字段示例：

{
  "transferredToAgent": true,
  "transferType": "QUEUE",
  "transferTime": "2026-08-10 15:30:45",
  "agentNumber": null,
  "queueNumber": "8001"
}

事件类型：CALL_INTENTION

推送字段说明

字段	类型	必填	说明
callId	string	是	通话唯一标识，用于关联通话记录和通话文本事件。
intentionLevel	string/null	否	意向度分析结果。HIGH：高意向，MEDIUM：中意向，LOW：低意向；UNRECOGNIZED：未识别
tags	array	是	意向标签数组；没有标签时为空数组。
tags[].code	string	是	标签编码。当前推送值与标签名称相同。
tags[].name	string	是	标签名称。
analysisVersion	integer	是	分析结果版本，当前为 1。
analysisCompletedAt	string	是	分析完成时间，格式为 yyyy-MM-dd HH:mm:ss。

同一通话重新分析时，可能产生新的意向事件。客户应使用 eventId 判断是否为重复推送，不应仅使用 callId 去重。

推送示例

{
  "eventId": "550e8400-e29b-41d4-a716-446655440001",
  "eventType": "CALL_INTENTION",
  "eventTime": "2026-08-10 15:31:20",
  "data": {
    "callId": "1054561235365715968",
    "intentionLevel": "HIGH",
    "tags": [
      {
        "code": "需要回电",
        "name": "需要回电"
      },
      {
        "code": "关注价格",
        "name": "关注价格"
      }
    ],
    "analysisVersion": 1,
    "analysisCompletedAt": "2026-08-10 15:31:20"
  }
}

事件类型：CALL_TRANSCRIPT

推送字段说明

字段	类型	必填	说明
callId	string	是	通话唯一标识，用于关联通话记录和意向事件。
items	array	是	对话文本明细数组，至少包含一条有效文本。
items[].sequence	integer	是	对话顺序号，从 1 开始。
items[].role	string	是	说话方角色，取值见下表。
items[].content	string	是	对话文本内容。
items[].timestamp	integer/null	否	对话时间戳，单位为毫秒。

role 取值：

值	说明
CUSTOMER	客户
ROBOT	语音机器人
AGENT	人工坐席
SYSTEM	系统或无法识别的角色

推送示例

{
  "eventId": "550e8400-e29b-41d4-a716-446655440002",
  "eventType": "CALL_TRANSCRIPT",
  "eventTime": "2026-08-10 15:31:00",
  "data": {
    "callId": "1054561235365715968",
    "items": [
      {
        "sequence": 1,
        "role": "ROBOT",
        "content": "您好，这里是售后回访。",
        "timestamp": 1786346888000
      },
      {
        "sequence": 2,
        "role": "CUSTOMER",
        "content": "你好，请讲。",
        "timestamp": 1786346893000
      }
    ]
  }
}

客户系统处理成功后，可返回空响应体，也可返回以下 JSON：

{
  "code": 200,
  "message": "success"
}

平台判定推送成功需同时满足：

HTTP 状态码为 2xx；
响应体为空，或响应 JSON 中的 code 为数字 `200` 或字符串 "200"。

字符串响应示例：

{
  "code": "200",
  "message": "success"
}

非 2xx、请求超时、连接失败、非 JSON 响应体或响应 code 不是 200，均会被判定为失败。失败事件可能被重新推送，因此客户系统必须按 eventId 做幂等处理。

2026-08-19

语音机器人事件推送

文档说明

对接准备

通用事件结构

事件推送

1.通话记录事件

2.通话意向事件

3.通话文本事件

4.回调响应

本页目录