事件

快速阅读

事件描述「已经发生了什么」，来源可以是服务端推送，也可以是 SDK 本地触发。常量在 AgentSDK.EventType。载荷里的 eventType 是事件名原文。

字段表保持原文。类型定义以类型为准。
transcript / TRANSCRIPT 是座席辅助实时转写，推给座席工作台。智能体通话中的实时转写用 RASR，挂机后按录音的转写用 ASR。不要把本事件改名为 RASR。
state / stateAction 的取值见状态机：状态/状态转移。

阅读地图

怎么订阅：读「1」。
按场景查事件名：读「2」。
按事件查字段：读「3」。
操作与事件的到达顺序见关键流程（时序图）。发起动作的方法见 API（操作）。

1. 订阅事件（on/off/once）

const { EventType } = AgentSDK;

const onStatus = (e) => console.log('agentStatus', e);
AgentSDK.on(EventType.AGENT_STATUS, onStatus);

AgentSDK.once(EventType.SESSION_INIT, () => console.log('session init'));

// 页面卸载时清理
AgentSDK.off(EventType.AGENT_STATUS, onStatus);

2. 事件目录（常用）

场景	事件名（`eventType`）	`EventType` 常量
座席状态	`agentStatus`	`AGENT_STATUS`
预览外呼：开始呼叫客户	`previewObCallStart`	`PREVIEW_OBCALL_START`
预览外呼：客户振铃	`previewObCallRinging`	`PREVIEW_OBCALL_RINGING`
预览外呼：桥接成功	`previewObCallBridge`	`PREVIEW_OBCALL_BRIDGE`
预览外呼：结果	`previewObCallResult`	`PREVIEW_OBCALL_RESULT`
咨询开始	`atxferStart`	`ATXFER_START`
咨询接通	`atxferLink`	`ATXFER_LINK`
咨询结束（恢复/挂断/取消）	`atxferEnded`	`ATXFER_ENDED`
咨询失败	`atxferError`	`ATXFER_ERROR`
咨询三方结果	`threewayAtxferResult`	`THREEWAY_ATXFER_RESULT`
咨询三方结束	`atxferThreewayUnlink`	`ATXFER_THREEWAY_UNLINK`
咨询转接完成	`completeAtxferResult`	`COMPLETE_ATXFER_RESULT`
振铃	`ringing`	`RINGING`
会话初始化/终止	`sessionInit` / `sessionTerminate`	`SESSION_INIT` / `SESSION_TERMINATE`
SIP 会话初始化/终止	`sipSessionInit` / `sipSessionTerminate`	`SIP_SESSION_INIT` / `SIP_SESSION_TERMINATE`
重连尝试	`reconnectAttempt`	`RECONNECT_ATTEMPT`
队列状态（班长）	`queueStatus`	`QUEUE_STATUS`
静默监听（结果/接通/结束）	`spyResult` / `spyLink` / `spyUnlink`	`SPY_RESULT` / `SPY_LINK` / `SPY_UNLINK`
三方通话（结果/接通/结束）	`threewayResult` / `threewayLink` / `threewayUnlink`	`THREEWAY_RESULT` / `THREEWAY_LINK` / `THREEWAY_UNLINK`
耳语辅导（结果/接通/结束）	`whisperResult` / `whisperLink` / `whisperUnlink`	`WHISPER_RESULT` / `WHISPER_LINK` / `WHISPER_UNLINK`
强插（结果/接通/结束）	`bargeResult` / `bargeLink` / `bargeUnlink`	`BARGE_RESULT` / `BARGE_LINK` / `BARGE_UNLINK`
强拆结果	`disconnectResult`	`DISCONNECT_RESULT`
强制签出结果	`setOfflineResult`	`SET_OFFLINE`
分机状态	`extenState`	`EXTENSTATE`
IVR 交互返回	`interactReturn`	`INTERACT_RETURN`
软电话断开	`sipDisconnected`	`SIP_DISCONNECTED`
座席辅助实时转写	`transcript`	`TRANSCRIPT`
预约回拨	`orderCallBack`	`ORDER_CALLBACK`
Ping（时延 / 网络）	`ping`	`PING`
WebRTC 统计（通话中每秒一次）	`webrtcStats`	`WEBRTC_STATS`

3. 事件载荷（字段级）

提示：state/stateAction 的取值定义见状态机：状态/状态转移。如果需要更严格的类型约束，请以类型为准。

3.1 agentStatus（座席状态）

当座席状态发生变化时触发。

字段	类型	说明
eventType	string	固定为 `agentStatus`
tenantId	string	租户 ID
agentNo	string	座席 ID
status	object	座席状态对象（`state/stateAction/initialStatus/deviceStatus/...`）

示例结构：

{
  eventType: 'agentStatus',
  tenantId: 't1',
  agentNo: '0001',
  status: {
    state: 'idle',
    stateAction: 'idle',
    initialStatus: 1,
    deviceStatus: 0
    // 当 deviceStatus=2/3/4 时，可能包含 callType/uniqueId/mainUniqueId 等字段
  }
}

3.2 previewObCallStart（预览外呼：开始呼叫客户）

字段	类型	说明
eventType	string	固定为 `previewObCallStart`
tenantId	string	租户 ID
agentNo	string	座席 ID
customerNumber	string	客户号码
customerNumberType	number	`0` 固话；`1` 手机
obClidAreaCode	string	客户区号
mainUniqueId	string	主通话唯一 ID
requestUniqueId	string	请求唯一 ID
obClid	string	外呼主叫显号

3.3 previewObCallRinging（预览外呼：客户振铃）

字段	类型	说明
eventType	string	固定为 `previewObCallRinging`
tenantId	string	租户 ID
agentNo	string	座席 ID
customerNumber	string	客户号码
customerNumberType	number	`0` 固话；`1` 手机
obClidAreaCode	string	客户区号
state	string	座席状态（`offline/invalid/idle/busy/calling/ringing/talking/wrapup`）
stateAction	string	状态动作（见状态机：状态/状态转移）
mainUniqueId	string	主通话唯一 ID

3.4 previewObCallBridge（预览外呼：桥接成功）

字段	类型	说明
eventType	string	固定为 `previewObCallBridge`
tenantId	string	租户 ID
agentNo	string	座席 ID
customerNumber	string	客户号码
customerNumberType	number	`0` 固话；`1` 手机
obClidAreaCode	string	客户区号
channel	string	通道名
destChannel	string	目标通道名
mainUniqueId	string	主通话唯一 ID

3.5 previewObCallResult（预览外呼：结果）

字段	类型	说明
eventType	string	固定为 `previewObCallResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
customerNumber	string	客户号码
result	string	`success` 表示接通；`error` 表示失败（如取消）
uniqueId	string	通话唯一 ID
obClid	string	外呼主叫显号

3.6 ringing

字段	类型	说明
eventType	string	固定为 `ringing`
tenantId	string	租户 ID
agentNo	string	座席 ID
callType	number	1 呼入；2 WebCall；4 预览外呼；5 预测外呼；6 外呼；9 内部呼叫；11 SIP 接入
channel	string	通道名
mainUniqueId	string	主通话唯一 ID
uniqueId	string	单条通话腿唯一 ID
customerNumber	string	客户号码
customerAreaCode	string	区号
customerProvince	string	省份
customerCity	string	城市
subCallType	number	子类型（101/102/103/...），用于区分转接/咨询/监听等场景
hotline	string	热线
numberTrunk	string	中继
queueNo	string	队列号
chanVariables	object	自定义变量

3.7 咨询事件：atxferStart / atxferLink / atxferEnded / atxferError

atxferStart（咨询开始）

字段	类型	说明
eventType	string	固定为 `atxferStart`
tenantId	string	租户 ID
agentNo	string	座席 ID
channel	string	通道名
destChannel	string	目标通道名
state	string	座席状态
stateAction	string	状态动作
mainUniqueId	string	主通话唯一 ID

atxferLink（咨询接通）

字段	类型	说明
eventType	string	固定为 `atxferLink`
tenantId	string	租户 ID
agentNo	string	座席 ID
channel	string	通道名
target	string	咨询目标
targetType	number	0 PSTN；1 座席；2 分机
state	string	座席状态
stateAction	string	状态动作

atxferEnded（咨询结束：恢复/挂断/取消）

字段	类型	说明
eventType	string	固定为 `atxferEnded`
tenantId	string	租户 ID
agentNo	string	座席 ID
target	string	咨询目标
targetType	number	0 PSTN；1 座席；2 分机
hangupSide	number	挂断方（咨询方或座席/客户）
state	string	座席状态
stateAction	string	状态动作

atxferError（咨询失败）

字段	类型	说明
eventType	string	固定为 `atxferError`
tenantId	string	租户 ID
agentNo	string	座席 ID
state	string	座席状态
stateAction	string	状态动作

3.8 threewayAtxferResult / atxferThreewayUnlink / completeAtxferResult

threewayAtxferResult（咨询三方结果）

字段	类型	说明
eventType	string	固定为 `threewayAtxferResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
target	string	咨询目标
targetType	number	0 PSTN；1 座席；2 分机
state	string	座席状态
stateAction	string	状态动作

atxferThreewayUnlink（咨询三方结束）

字段	类型	说明
eventType	string	固定为 `atxferThreewayUnlink`
tenantId	string	租户 ID
agentNo	string	座席 ID
target	string	咨询目标
targetType	number	0 PSTN；1 座席；2 分机
state	string	座席状态
stateAction	string	状态动作

completeAtxferResult（咨询转接完成）

字段	类型	说明
eventType	string	固定为 `completeAtxferResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
target	string	咨询目标
targetType	number	0 PSTN；1 座席；2 分机
state	string	座席状态
stateAction	string	状态动作

3.9 reconnectAttempt

SDK 即将执行重连尝试时触发。最大尝试次数为 20，超过后通常需要座席重新登录。

字段	类型	说明
eventType	string	固定为 `reconnectAttempt`
attempt	number	当前尝试次数（从 1 开始）
code	number	`0` 已重连；`-1` 断开中
firstAttemptTs	number	开始进入重连循环时的时间戳（毫秒）
maxAttempts	number	最大尝试次数（固定为 20）
sinceFirstAttemptMs	number	距离首次尝试已过去的毫秒数

3.10 queueStatus（班长）

字段	类型	说明
eventType	string	固定为 `queueStatus`
queueStatus	object	Map 结构：`{ "<queueNo>": { queueParams, agentStatuses, queueEntries } }`

队列相关类型见类型。

3.11 spyResult / spyLink / spyUnlink（静默监听）

spyResult

字段	类型	说明
eventType	string	固定为 `spyResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
spiedCno	string	被监听座席 ID
initiator	string	监听发起方
initiatorType	number	0 PSTN；1 座席；2 分机
uniqueId	string	通话唯一 ID
result	string	`success` 或 `error`

spyLink

字段	类型	说明
eventType	string	固定为 `spyLink`
tenantId	string	租户 ID
agentNo	string	座席 ID
spiedCno	string	被监听座席 ID
initiator	string	监听发起方
initiatorType	number	0 PSTN；1 座席；2 分机
result	string	`success` 或 `error`
channel	string	通道名

spyUnlink

字段	类型	说明
eventType	string	固定为 `spyUnlink`
tenantId	string	租户 ID
agentNo	string	座席 ID
spiedCno	string	被监听座席 ID
initiator	string	监听发起方
initiatorType	number	0 PSTN；1 座席；2 分机

3.12 threewayResult / threewayLink / threewayUnlink（班长三方）

threewayResult

字段	类型	说明
eventType	string	固定为 `threewayResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
threewayedCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
uniqueId	string	通话唯一 ID
result	string	`success` 或 `error`

threewayLink

字段	类型	说明
eventType	string	固定为 `threewayLink`
tenantId	string	租户 ID
agentNo	string	座席 ID
threewayedCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
channel	string	通道名

threewayUnlink

字段	类型	说明
eventType	string	固定为 `threewayUnlink`
tenantId	string	租户 ID
agentNo	string	座席 ID
threewayedAgentNo	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机

3.13 whisperResult / whisperLink / whisperUnlink（耳语辅导）

whisperResult

字段	类型	说明
eventType	string	固定为 `whisperResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
whisperedCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
uniqueId	string	通话唯一 ID
result	string	`success` 或 `error`

whisperLink

字段	类型	说明
eventType	string	固定为 `whisperLink`
tenantId	string	租户 ID
agentNo	string	座席 ID
whisperedCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
channel	string	通道名

whisperUnlink

字段	类型	说明
eventType	string	固定为 `whisperUnlink`
tenantId	string	租户 ID
agentNo	string	座席 ID
whisperedAgentNo	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机

3.14 bargeResult / bargeLink / bargeUnlink（强插）

bargeResult

字段	类型	说明
eventType	string	固定为 `bargeResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
bargedAgentNo	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
uniqueId	string	通话唯一 ID
result	string	`success` 或 `error`

bargeLink

字段	类型	说明
eventType	string	固定为 `bargeLink`
tenantId	string	租户 ID
agentNo	string	座席 ID
bargedAgentNo	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
channel	string	通道名

bargeUnlink

字段	类型	说明
eventType	string	固定为 `bargeUnlink`
tenantId	string	租户 ID
agentNo	string	座席 ID
bargedCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机

3.15 disconnectResult（强拆结果）

字段	类型	说明
eventType	string	固定为 `disconnectResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
disconnectorCno	string	目标座席 ID
initiator	string	发起方
initiatorType	number	0 PSTN；1 座席；2 分机
uniqueId	string	通话唯一 ID
result	string	`success` 或 `error`

3.16 setOfflineResult（强制签出结果）

字段	类型	说明
eventType	string	固定为 `setOfflineResult`
tenantId	string	租户 ID
agentNo	string	座席 ID
initiator	string	发起强制签出的人（班长座席号或管理员名称）
code	string	`0` 成功；`-1` 失败
message	string	提示信息（通常为 `ok`）

3.17 orderCallBack（预约回拨）

该事件是存在的（eventType=orderCallBack，EventType.ORDER_CALLBACK），但当前源文档没有给出字段级载荷契约。

建议做法：

将其当作透传事件处理，并基于 eventType=orderCallBack 分支
如果业务必须依赖具体字段，请在集成前与后端团队确认载荷契约

3.18 extenState（分机状态）

字段	类型	说明
eventType	string	固定为 `extenState`
state	string	`Reachable` / `Unreachable`
registerState	string	`Registered` / `Unregistered`
registerTime	string	注册时间（例如 `2024-01-01 10:54:19`）
expirationTime	string	过期时间
extenIp	string	话机 IP
URI	string	注册 URI
extenNo	string	分机号
tenantId	string	租户 ID

3.19 interactReturn（IVR 交互返回）

字段	类型	说明
eventType	string	固定为 `interactReturn`
tenantId	string	租户 ID
agentNo	string	座席 ID
returnVariables	object	返回变量（通过 `transferIvr` 传入）

3.20 sipDisconnected（软电话断开）

当软电话连接中断时触发。大多数情况下，座席需要重新登录或重建软电话会话。

3.21 transcript（座席辅助实时转写）

事件名是 transcript。它把座席辅助实时转写推给座席工作台。智能体通话中的实时转写用 RASR，挂机后按录音的转写用 ASR。字段名保持原文。旧稿里的 transcriptEvent 或 rasr 不是本 SDK 对外的 eventType。

字段	类型	说明
eventType	string	固定为 `transcript`
text	string	转写后的句子文本
role	number	`1` 座席侧；`2` 客户侧
transcriptTime	number	文本生成时的绝对时间戳（毫秒）
beginTime	number	相对录音开始时间的起始点（毫秒）
endTime	number	相对录音开始时间的结束点（毫秒）
finished	number	`1` 已结束；`0` 进行中
sentenceIndex	number	句子序号，从 0 开始
sentenceType	string	`intermediateResult` / `sentenceEnd`
mainUniqueId	string	主通话唯一 ID
sentenceBeginTimestamp	number	该句引擎开始处理的时间戳（毫秒，仅 `sentenceEnd` 返回）
sentenceEndTimestamp	number	最终文本返回的时间戳（毫秒，仅 `sentenceEnd` 返回）

3.22 ping（时延 / 网络质量）

字段	类型	说明
eventType	string	固定为 `ping`
latencyTime	number	Ping 时延，单位毫秒
networkState	number	基于时延计算出的网络质量分档

3.23 webrtcStats（WebRTC 通话统计）

需要在 setup() 中开启 webrtcStats=true（或由租户侧启用）。在软电话通话期间，每秒派发一次。

该载荷较大，建议按类型中的 WebrtcStatsEvent 处理。关键字段包括：

iceState、dtlsState
packetsSent/packetsReceived、packetsState
jitter、rtt、packetLossRate
sentNetworkQuality、receivedNetworkQuality

4. 典型时序

关键事件时序（如预览外呼、咨询流程）请参见关键流程（时序图）。