语音机器人事件推送

语音机器人平台通过 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 做幂等处理。

中文描述	英文标识
未识别	unknown
禁止呼叫	forbidden
服务不可用	serviceUnavailable
请求终止	cancel
呼叫超时	requestTimeout
被叫未接听	decline
被叫忙	calledBusy
空号	notFound
停机	outOfService
关机	phoneOff
电话忙	lineBusy
秘书台	secretaryDesk
号码正忙	numberBusy
呼叫等待	callWaiting
正在通话	onThePhone
无法接通	callUnavailable
无人接听	noAnswer
无法接听	cannotAnswer
稍后再拨	callLater
无权接受	noRightToAccept
不方便接听	inconvenientAnswer
不在服务区	notInService
前转不成功	forwardTurnUnsuccessful
不要挂机	doNotHangUp
通话中	inCall
暂停服务	pauseService
没有应答	noResponse
用户忙	userBusy
加拨零	dailAddAero
线路黑名单	lineBlackList
网络忙	networkBusy
无子业务号码	noSubBusinessNumber
无此业务号码	noSuchBusinessNumber
号码不存在	numberNotExist

2026-09-24

语音机器人事件推送

文档说明

对接准备

通用事件结构

事件推送

1.通话记录事件

2.通话意向事件

3.通话文本事件

4.回调响应

语音机器人失败原因枚举

本页目录