事件

说明：

事件用于描述“发生了什么”（可能来自服务端推送，也可能由 SDK 本地触发）。

事件常量通过 AgentSDK.EventType（或等价枚举）暴露。

每个事件载荷通常都包含一个 eventType 字符串，用于标识事件类型。

06-Types.md 中的类型定义是最终准确依据。本文档主要提供字段级载荷表和集成实践说明。

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 的取值定义见 08-State-Machine-stateAction.md。如果需要更严格的类型约束，请以 06-Types.md 为准。

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	状态动作（见 `08-State-Machine-stateAction.md`）
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 } }`

队列相关类型见 06-Types.md。

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（实时转写）

命名说明：旧文档中可能会提到 transcriptEvent 或 rasr。SDK 对外公开的 eventType 是 transcript。

字段	类型	说明
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（或由租户侧启用）。在软电话通话期间，每秒派发一次。

该载荷较大，建议按 06-Types.md 中的 WebrtcStatsEvent 处理。关键字段包括：

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

4. 典型时序

关键事件时序（如预览外呼、咨询流程）请参见 10-Key-Flows-Sequence-Diagrams.md。