快速入门

目标：帮助你尽快跑通一个最小可用的端到端流程：
登录 → 订阅关键事件 → 发起预览外呼 → 接听/挂断（软电话）。

0. 前置条件

需要使用 HTTPS（尤其是 WebRTC 软电话场景）
baseURL 必须可访问
准备好登录参数：tenantId、agentNo、sessionKey、bindEndpoint

1. 安装 / 引入

1.1 UMD

<!-- UMD 全局对象：window.AgentSDK（以你的实际构建产物为准） -->
<script src="/path/to/agent-sdk.umd.min.js"></script>

1.2 npm / ESM

pnpm add @cc/agent-sdk
# 或 npm i / yarn add

import { AgentJsSDK as AgentSDK } from '@cc/agent-sdk';

2. 初始化（setup）

在应用启动时调用一次 setup()，完成 SDK 配置：

// UMD 示例
const AgentSDK = window.AgentSDK.default;

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

配置项详情请参见 04-API-Operations.md → setup。

3. 登录（login）

await AgentSDK.login({
  tenantId: 'your_tenantId',
  agentNo: 'your_agentNo',
  sessionKey: 'your_sessionKey',
  bindEndpoint: { endpointType: 1, endpoint: '13600000000' }, // 1 PSTN；2 分机；3 软电话
  initialStatus: 1 // 1 空闲；2 忙碌（需要 pauseDescription）；3 整理态
  // pauseDescription: 'MEETING'
});

4. 订阅关键事件

建议尽早订阅（可在登录前或登录后），以免错过早期事件。页面卸载时记得始终调用 off 清理监听。

const { EventType } = AgentSDK;

AgentSDK.on(EventType.AGENT_STATUS, (e) => console.log('agentStatus', e));
AgentSDK.on(EventType.PREVIEW_OBCALL_RINGING, (e) => console.log('ringing', e));
AgentSDK.on(EventType.PREVIEW_OBCALL_BRIDGE, (e) => console.log('bridge', e));
AgentSDK.on(EventType.RECONNECT_ATTEMPT, (e) => console.log('reconnect', e));

完整事件列表与载荷请参见 05-Events.md；类型定义请参见 06-Types.md。

5. 发起预览外呼（previewObCall）

const res = await AgentSDK.previewObCall({
  customerNumber: '13800138000',
  agentAnswerTimeout: 30,
  customerAnswerTimeout: 45,
  // 通道变量示例。详见 `06-Types.md` 中的 ChannelVariable。
  // chanVariables: [{ name: 'k1', value: 'v1', type: 1 }]
});

if (res.code !== 0) {
  console.error('previewObCall 失败：', res.errorCode, res.message);
}

典型事件时序请参见 10-Key-Flows-Sequence-Diagrams.md。

6. 接听 / 挂断（WebRTC 软电话）

当 bindEndpoint.endpointType = 3（软电话）时：

await AgentSDK.sipLink();    // 接听
await AgentSDK.sipUnlink();  // 挂断

7. 登出与清理

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

// 清理示例：
// AgentSDK.off(EventType.AGENT_STATUS, handler);

8. 推荐的错误处理模式

你必须同时处理以下两类情况：

Promise 已 resolve，但 res.code !== 0（服务端业务失败）
Promise reject / throw（SDK 本地错误或运行时异常）

try {
  const res = await AgentSDK.previewObCall({ customerNumber: '13800138000' });
  if (res.code !== 0) {
    console.error('[服务端失败]', res.errorCode, res.message);
    return;
  }
} catch (err) {
  console.error('[SDK 错误或运行时错误]', err);
}

详见错误处理。