核心概念与生命周期

快速阅读

AgentSDK 的使用顺序是：setup → 订阅长期事件 → login → 用 Promise 判断操作结果、用事件驱动界面 → logout 并 off。

• 通话控制（外呼、保持、转接、班长监控）放在登录成功之后。
• uniqueId 标识一条通话腿，mainUniqueId 串联整通通话。
• state 是粗粒度座席状态，stateAction 是更细的动作或原因。
• 断线后 SDK 自动重连，maxAttempts 固定为 20。

阅读地图

• 生命周期四段：读「二」。
• 操作响应和事件怎么配合：读「三」。
• 标识和状态字段：读「四」「五」。
• 重连和班长查队列：读「六」「七」。
• 时序见 关键流程（时序图），取值见 状态机：状态/状态转移。

一、文档说明

本文说明 AgentSDK 会话从初始化到登出的对象和顺序，便于座席工作台集成时把操作和事件放在正确的阶段。

字段结构以 类型 为准。

二、生命周期

2.1 初始化

• 应用启动时调用一次 setup(config)。
• 尽早注册长期存在的事件处理器，例如 AGENT_STATUS、RECONNECT_ATTEMPT。

2.2 登录

• 调用 login(params) 建立会话。
• 登录成功后再执行通话控制：外呼、保持、转接、质检 / 班长监控。

2.3 运行

• 用 Promise 响应判断操作是否被接受、是否执行成功。
• 用事件驱动界面和业务流程：振铃、桥接、座席状态变化。

2.4 登出

• 调用 logout()。
• 对已注册的事件处理器使用 off 移除监听。

三、操作与事件

SDK 有两条信息通道：

• 操作响应（Promise resolve）：后端是否接受并执行了该操作。
• 事件（on / off / once）：通话生命周期里实际发生了什么。

调用 previewObCall() 时，先收到 previewObCallResp，成功后再收到 previewObCallStart、previewObCallRinging、previewObCallBridge、previewObCallResult 等事件。

完整时序见 关键流程（时序图）。

四、uniqueId 与 mainUniqueId

• uniqueId：单条通话腿（单通道）的唯一标识。
• mainUniqueId：主通话唯一标识，用来串联一整条通话链路。

许多状态更新（例如 agentStatus）在 deviceStatus=3/4（振铃 / 通话中）时带上这两个字段。结构以 类型 为准。

五、state 与 stateAction

许多事件载荷包含：

• state：粗粒度座席状态，例如 idle / busy / ringing / talking。
• stateAction：更细的动作或原因，例如预览外呼客户振铃、保持、开始咨询。

可以用它们控制按钮和操作保护。例如只有 talking 时允许 hold。取值见 状态机：状态/状态转移。

六、重连（reconnectAttempt）

断线后 SDK 自动重连，并派发：

• attempt：当前尝试次数，从 1 开始。
• maxAttempts：最大尝试次数，固定为 20。

监听 RECONNECT_ATTEMPT。超过最大次数后提示重新登录。外呼、转接、班长操作放在已登录且 WebSocket 可用之后。载荷见 事件。

七、队列与班长

班长 / 质检监控：

• getQueueStatus() 按需查询。
• queueStatus 事件接收队列指标、队列成员和排队来电。

类型见 类型。