API（操作）

说明：

本文档描述通过 SDK 方法发起的操作。

所有操作都返回 Promise。通过已解析响应中的 code 判断成功/失败。使用 try/catch 处理本地异常（参见错误处理

类型定义位于类型。如果与其他文件存在不一致，以该文件为准。

1. 通用约定

1.1 标准签名

AgentSDK.methodName(params?): Promise<SdkResponse & {...}>

1.2 标准响应字段（摘要）

action：操作名称（通常与响应事件 / EventType 对齐）
code：0 表示成功；非 0 表示失败（常见为 -1）
message：人类可读的消息
errorCode?：可选的业务错误码（领域相关）

参见 06-Types.md。

1.3 两种结果消费方式

Promise（推荐）：使用 await AgentSDK.xxx() 获取操作响应
事件：订阅 EventType.XXX_RESP（或 xxxResp）通过事件接收响应

2. 配置与事件处理

2.1 setup(config)

用途：设置全局 SDK 配置（建议在应用启动时执行一次）。

常用参数：

参数	类型	必填	说明	默认值
baseURL	string	是	Agent Gateway 基础 URL	无
webrtc	boolean	否	启用 WebRTC 软电话	true
debug	boolean	否	启用控制台日志	false
audio_debug	boolean	否	启用音频播放/暂停调试日志	false
observability	boolean	否	启用可观测性上报（仅限由 SDK 触发的自定义事件/错误）	false
webrtcStats	boolean	否	发出 `webrtcStats` 事件（软电话通话质量）	false

示例：

AgentSDK.setup({
  baseURL: 'https://api.example.com',
  debug: false,
  webrtc: true,
  webrtcStats: false,
  audio_debug: false,
  observability: false
});

2.2 事件 API：on/off/once

订阅：AgentSDK.on(eventName, handler)
取消订阅：AgentSDK.off(eventName, handler)
订阅一次：AgentSDK.once(eventName, handler)

示例：

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 once'));

// Cleanup on unload
AgentSDK.off(EventType.AGENT_STATUS, onStatus);

3. 坐席操作（核心）

3.1 login(params)

用途：坐席登录（建立会话、打开 WebSocket、订阅服务端推送事件）。

参数（详细）

参数	类型	必填	说明
sessionKey	string	是	会话凭证（有效期由服务端控制）
tenantId	string	是	租户 ID
agentNo	string	是	坐席 ID
webSocketUrl	string	否	WebSocket URL（省略时从 `baseURL` 推导）
bindEndpoint	BindEndpoint	是	坐席终端：`{ endpointType: 1\|2\|3, endpoint: string }` - `1`：PSTN 号码 - `2`：分机 - `3`：软电话
qids	string	否	仅主管可用：队列列表（call-center-id + queueNo），逗号分隔
initialStatus	number	是	初始状态：`1` 空闲；`2` 忙碌；`3` 收尾
pauseDescription	string	条件必填	当 `initialStatus=2`（忙碌）时必填：忙碌原因说明（必须已在租户中配置）
workMode	string	否	坐席工作模式：`0` 预览 + 预测；`4` 仅预览；`5` 仅预测（逗号分隔）

响应（Promise 解析结果）

除基础 SdkResponse 外，login 还可能返回与软电话相关的字段（仅软电话）。

字段	类型	说明
action	string	固定为 `loginResp`
code	number	`0` 成功；`-1` 失败
message	string	消息（成功时通常为 `ok`）
tenantId	string	租户 ID
agentNo	string	坐席 ID
bindEndpoint	BindEndpoint	`bindEndpoint` 的回显
webrtcSocketUrl	string	软电话：WebRTC socket URL
webrtcStunServer	string	软电话：STUN 服务器配置
sipPwd	string	软电话：SIP 密码
sipIp	string	软电话：SIP IP

示例

const res = await AgentSDK.login({
  tenantId: 'your_tenantId',
  agentNo: 'your_agentNo',
  sessionKey: 'your_sessionKey',
  bindEndpoint: { endpointType: 1, endpoint: '13600000000' },
  initialStatus: 1
  // initialStatus=2 requires pauseDescription: 'MEETING'
});

if (res.code === 0) {
  console.log('login ok');
} else {
  console.error('login failed:', res.message);
}

3.2 logout(params)

用途：登出 / 断开连接。

参数（详细）

参数	类型	必填	说明
logoutMode	number	是	`0`：从服务端断开浏览器连接（坐席在 CC 中仍保持在线） - `1`：从 CC 完全登出
unbindEndpoint	number	否	`0` 保持绑定；`1` 解绑；默认 `0`。仅在 `logoutMode=1` 时生效。

await AgentSDK.logout({ logoutMode: 1, unbindEndpoint: 0 });

3.3 pause(params) / unpause()

用途：设置忙碌 / 设置空闲。

pause(params) 参数

参数	类型	必填	说明
pauseType	number	是	忙碌类型（租户配置）。常见值：`0` 生产性忙碌；`2` 非生产性忙碌（以实际枚举为准）
pauseDescription	string	否	忙碌原因说明（默认“busy”），必须存在于租户配置中

响应消息说明

message 可能包含（示例）：ok、deviceStatus not in idle、exception、fail to get lock、already ready、not logined、no such agent。

await AgentSDK.pause({ pauseType: 1, pauseDescription: 'MEETING' });
await AgentSDK.unpause();

3.4 updateBoundEndpoint(params)

用途：修改坐席绑定终端（电话/分机等）。

参数	类型	必填	说明
bindEndpoint	BindEndpoint	是	新终端

await AgentSDK.updateBoundEndpoint({
  bindEndpoint: { endpointType: 1, endpoint: '13600000000' }
});

4. 呼叫控制（通用）

4.1 previewObCall(params)

用途：预览外呼（先振铃坐席终端，再拨打客户并桥接）。

软电话说明：当 bindEndpoint.endpointType=3 时，仅应在软电话准备就绪/注册完成后再发起外呼（取决于你的集成方式）。

参数（详细）

参数	类型	必填	说明
customerNumber	string	是	客户电话号码
agentAnswerTimeout	number	否	坐席振铃超时（默认 30，范围 5–60 秒）
customerAnswerTimeout	number	否	客户振铃超时（默认 45，范围 5–60 秒）
obClid	string	否	外呼主叫号码（必须属于当前租户）
obClidAreaCode	string	否	外呼主叫号码区号
obClidGroup	string	否	主叫号码组（需要租户开通相关能力）
chanVariables	ChannelVariable[]	否	用于事件负载/CDR 自定义字段/SIP Header 透传的通道变量（最多 5 个）
requestUniqueId	string	否	客户端请求 ID（省略时自动生成）
backupNumber	string	否	备用号码（逗号分隔，最多 5 个）
cdrIsAsr	number	否	录音启用 ASR：`0` 否；`1` 是（默认 1）

const res = await AgentSDK.previewObCall({
  customerNumber: '13800138000',
  agentAnswerTimeout: 30,
  customerAnswerTimeout: 45
});
if (res.code !== 0) console.error(res.errorCode, res.message);

相关事件：previewObCallStart/previewObCallRinging/previewObCallBridge/previewObCallResult（参见 05-Events.md、10-Key-Flows-Sequence-Diagrams.md）。

业务错误码（预览外呼）

当 res.code !== 0 时，可能返回 errorCode/message（以下为示例，以服务端为准）：

errorCode	message	说明
10001	Please try again later	系统异常
20000	bad param	参数无效（例如号码中包含特殊字符）
20011	previewOutcall agent busy	坐席忙碌（通话中/拨号中等）
20012	no such agent	坐席不存在或离线
20016	permission denied	无外呼权限
20024	no ob permission	未启用外呼能力
20025	bad destInterface	分机未注册
20031	restrict tel	号码在黑名单中或不在白名单中
20032	bad obClidLeftNumber	主叫号码不属于当前租户
20101	previewOutcall not within the time allowed	外呼时间受限
20102	bad tel	电话号码格式无效
20103	fail to get lock	锁定坐席失败

4.2 cancelPreviewObCall()

用途：取消预览外呼（通常在坐席终端振铃期间）。

await AgentSDK.cancelPreviewObCall();

4.3 unlink(params)

用途：挂断当前通话。

参数	类型	必填	说明
side	number	否	挂断侧：`1` 坐席侧；`2` 客户侧（默认 1）

await AgentSDK.unlink({ side: 1 });

4.4 reject(params)

用途：在振铃时拒接来电。

参数	类型	必填	说明
description	string	否	拒接说明（长度 < 20）

await AgentSDK.reject({ description: 'busy' });

4.5 hold() / unhold()

用途：保持 / 恢复通话。

await AgentSDK.hold();
await AgentSDK.unhold();

4.6 mute(params) / unmute(params)

用途：静音 / 取消静音通话。

参数	类型	必填	说明
direction	string	是	`in`（入方向音频）、`out`（出方向音频）、`all`（双向）。默认 `in`。

await AgentSDK.mute({ direction: 'in' });
await AgentSDK.unmute({ direction: 'in' });

4.7 sendDtmf(params)

用途：在通话中发送 DTMF 按键。

参数	类型	必填	说明
digits	string	是	DTMF 按键字符串（最多 20 个字符）
target	number	是	`1` 发送到本地链路；`2` 发送到远端链路
durationMs	number	否	每个按键持续时长（默认 100，范围 100–500 ms）
gapMs	number	否	按键间隔（默认 250，范围 250–1000 ms）

await AgentSDK.sendDtmf({ digits: '1#', target: 2 });

4.8 performSatisfactionSurvey()

用途：发起客户满意度调查。成功后，坐席侧通话结束，客户进入满意度调查流程。

await AgentSDK.performSatisfactionSurvey();

4.9 InternalCall(params)

用途：向同一租户内的其他坐席或 IP 电话分机发起内部呼叫。

参数	类型	必填	说明
targetType	number	是	`0` 坐席；`1` 分机
target	string	是	被叫标识： - `targetType=0`：`agentNo` - `targetType=1`：分机号
agentAnswerTimeout	number	否	坐席振铃超时（默认 30，范围 5–60 秒）
customerAnswerTimeout	number	否	被叫振铃超时（默认 45，范围 5–60 秒）
requestUniqueId	string	否	请求唯一 ID（省略时自动生成）
chanVariables	ChannelVariable[]	否	通道变量（如需持久化到 CDR，需租户配置支持）

await AgentSDK.InternalCall({
  targetType: 0,
  target: '0000',
  agentAnswerTimeout: 30,
  customerAnswerTimeout: 45
});

4.10 prolongWrapup(params)

用途：延长收尾时间。

参数	类型	必填	说明
wrapupTime	number	是	额外收尾时间（秒，范围 30–600）

await AgentSDK.prolongWrapup({ wrapupTime: 300 });

4.11 startAutoObCallTask(params)

用途：启动坐席自动外呼任务。

参数	类型	必填	说明
taskId	string	是	自动外呼任务 ID
callParams	string	否	呼叫配置（JSON 字符串）

await AgentSDK.startAutoObCallTask({ taskId: '11', callParams: '{"key":"value"}' });

4.12 pauseAutoObCallTask(params)

用途：暂停坐席自动外呼任务。

参数	类型	必填	说明
taskId	string	是	自动外呼任务 ID

await AgentSDK.pauseAutoObCallTask({ taskId: '11' });

4.13 changeObCallMode(params)

用途：切换坐席外呼工作模式。

参数	类型	必填	说明
workMode	number	是	`0` 预览 + 预测；`1` 仅预览；`2` 仅预测

await AgentSDK.changeObCallMode({ workMode: 0 });

5. 咨询与转接（通话转接功能）

5.1 startAtxfer(params) / cancelAtxfer() / resumeAtxfer()

用途：发起咨询 / 取消咨询 / 从咨询中恢复。

startAtxfer(params) 参数

参数	类型	必填	说明
targetType	number	是	`0` PSTN；`1` 坐席；`2` 分机
target	string	是	根据 `targetType` 指定的目标标识
chanVariables	ChannelVariable[]	否	变量（例如 `[{ name:'test', value:'123', type:1 }]`）

await AgentSDK.startAtxfer({ targetType: 0, target: '13800138000' });
await AgentSDK.cancelAtxfer();
await AgentSDK.resumeAtxfer();

5.2 completeAtxfer(params)

用途：完成咨询转接。

可选参数：

参数	类型	必填	说明
durationLimit	number	否	通话时长限制（秒，默认：不限）
preAlertSeconds	number	否	预提醒秒数（默认 60，在设置 `durationLimit` 时生效）
preAlertAudioFile	string	否	预提醒音频文件名（在设置 `durationLimit` 时生效）

await AgentSDK.completeAtxfer();

5.3 threewayAtxfer(params)

用途：咨询三方通话。

可选参数：

参数	类型	必填	说明
durationLimit	number	否	通话时长限制（秒，默认：不限）
preAlertSeconds	number	否	预提醒秒数（默认 60，在设置 `durationLimit` 时生效）
preAlertAudioFile	string	否	预提醒音频文件名（在设置 `durationLimit` 时生效）

await AgentSDK.threewayAtxfer();

5.4 blxfer(params)

用途：盲转（到客户号码 / 坐席 / 分机 / IVR 节点）。

参数	类型	必填	说明
targetType	number	是	`0` 客户号码 - `1` 坐席 - `2` 分机 - `3` IVR 节点
target	string	是	目标标识： - 类型 0：客户号码 - 类型 1：agentNo - 类型 2：分机号 - 类型 3：JSON 字符串 `{"ivrId":"<ivrId>","ivrNode":"<ivrNode>"}`
blxferVariables	ChannelVariable[]	否	转接变量（跨部门等；最多 5 个）
blxferDialSayAgent	number	否	`0` 不播报坐席 ID；`1` 播报
blxferDialAgentHold	number	否	`0` 不播放“正在为您接通客户”；`1` 播放

await AgentSDK.blxfer({ targetType: 0, target: '13800138000' });

详见 09-Transfer-Parameters-blxferVariables.md。

5.5 transferIvr(params)

用途：转接到 IVR 进行交互，并在 interactReturn 中接收返回变量。

参数	类型	必填	说明
ivrTarget	object	是	`{ ivrId: string\|number, ivrNode: string }`
chanVariables	ChannelVariable[]	否	通道变量（最多 5 个）
returnVariables	object	否	返回变量映射（通过 `interactReturn` 返回）

await AgentSDK.transferIvr({
  ivrTarget: { ivrId: 1, ivrNode: '1.1' }
});

相关事件：interactReturn（参见 05-Events.md）。

6. 软电话（WebRTC）

6.1 sipLink() / sipUnlink()

用途：软电话接听/挂断（bindEndpoint.endpointType=3）。

await AgentSDK.sipLink();
await AgentSDK.sipUnlink();

相关事件：sipSessionInit/sipSessionTerminate/sipDisconnected/webrtcStats（参见 05-Events.md）。

7. 主管 / 监控操作

主管通常需要在登录时绑定队列（例如 qids）并具备相应权限。

7.1 setPause(params) / setUnpause(params)

用途：主管将目标坐席设置为忙碌/空闲。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.setPause({ agentNo: '0000' });
await AgentSDK.setUnpause({ agentNo: '0000' });

7.2 spy(params) / unspy()

用途：开始/停止通话监听（静默监听）。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.spy({ agentNo: '0000' });
await AgentSDK.unspy({ agentNo: '0000' });

7.3 performThreeway(params) / cancelThreeway(params)

用途：主管在目标坐席的通话上发起三方通话 / 取消三方通话。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.performThreeway({ agentNo: '0000' });
await AgentSDK.cancelThreeway({ agentNo: '0000' });

7.4 whisper(params) / unWhisper()

用途：开始/停止对目标坐席通话的耳语辅导。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.whisper({ agentNo: '0000' });
await AgentSDK.unWhisper({ agentNo: '0000' });

7.5 barge(params) / disconnect(params)

用途：强插 / 强制断开目标坐席的通话。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.barge({ agentNo: '0000' });
await AgentSDK.disconnect({ agentNo: '0000' });

7.6 pickup(params)

用途：代接（代替目标坐席接听振铃中的来电）。

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID

await AgentSDK.pickup({ agentNo: '0000' });

7.7 setOnline(params) / setOffline(params)

用途：强制将坐席设为在线/离线。

setOnline(params)

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID
bindEndpoint	BindEndpoint	是	绑定终端（主管示例通常使用 PSTN/分机）

await AgentSDK.setOnline({
  agentNo: '0000',
  bindEndpoint: { endpointType: 1, endpoint: '1354*******' }
});

setOffline(params)

参数	类型	必填	说明
agentNo	string	是	目标坐席 ID
unbindEndpoint	number	否	`0` 保持绑定；`1` 解绑；默认 `0`

await AgentSDK.setOffline({ agentNo: '0000', unbindEndpoint: 0 });

7.8 getQueueStatus(params)

用途：查询队列状态（主管）。

参数	类型	必填	说明
queueNos	any[]	否	队列号列表
fields	string	否	请求的区段：`queueParams`、`agentStatuses`、`queueEntries`（逗号分隔）

响应（摘要）：

action：queueStatus
queueStatus：queueNo → data 的映射（参见 06-Types.md）

await AgentSDK.getQueueStatus({ queueNos: [0, 1, 2], fields: 'queueParams,agentStatuses,queueEntries' });

7.9 ListPreviewDialingTask()

用途：获取预览拨号任务列表。

注意：源文档显示返回负载尚未完全定义。本文件仅说明该 API 存在并遵循标准响应结构；具体返回字段请与服务端契约确认。

await AgentSDK.ListPreviewDialingTask();