CTICloud AgentSDK 集成到 OpenClaw
快速阅读
本文说明怎样把 AgentSDK 文档和业务需求交给 OpenClaw,生成座席工作台页面,再由人核对登录、外呼和事件。
- AgentSDK 提供 Promise 操作、WebSocket 事件和 WebRTC 软电话。OpenClaw 用来读文档并生成业务代码。
- 集成前准备 Agent Gateway 地址、
tenantId、座席工号、sessionKey、终端类型和终端号码。 - 生成结果仍要按 错误处理 同时处理
code !== 0和AgentSdkError。
阅读地图
- OpenClaw 要读哪些 SDK 文档、需求怎么写:读「二」「三」。
- 可直接对照的代码:读「四」。
- 操作名索引:读「五」。状态和终端枚举:读「六」。
- 参数以 API(操作) 和 类型 为准,不要只依赖生成代码。
一、文档说明
本文面向要用 OpenClaw 把 AgentSDK 嵌进自有座席工作台的开发人员。OpenClaw 是开发助手:阅读下面列出的文档,按需求描述生成代码,并按后续指令调整。
AgentSDK
- Operations:Promise 风格的操作 API。
- Events:经 WebSocket 推送的事件。
- Softphone:基于 WebRTC 的语音通话。
OpenClaw
把 SDK 文档链接和结构化需求交给 OpenClaw。它解析文档中的 API 与事件,再按需求生成或修改页面代码。生成后仍要人工核对参数、事件订阅和异常分支。
二、前置准备
2.1 环境
| 项目 | 要求 |
|---|---|
| 浏览器 | Chrome 80+ / Edge 80+ / Firefox 75+ |
| 协议 | HTTPS(软电话场景必需) |
| OpenClaw | 已部署并可访问 |
2.2 参数
| 参数 | 说明 |
|---|---|
| Base URL | Agent Gateway 服务地址 |
| Tenant ID | 租户标识 |
| Agent No | 座席工号 |
| SessionKey | 登录凭证(由业务后端生成) |
| Endpoint Type | 终端类型:1=PSTN,2=分机,3=软电话 |
| Endpoint | 终端号码 |
三、集成步骤
3.1 提供 SDK 文档
将下列文档交给 OpenClaw:
请阅读并记住以下文档:
/docs/product-integration-overview
/docs/quick-start
/docs/core-concepts-lifecycle
/docs/api-operations
/docs/types
/docs/error-handling
3.2 描述业务需求
用结构化描述,写清功能清单、业务场景、已知参数和约束。
| 要素 | 说明 | 示例 |
|---|---|---|
| 功能清单 | 需要实现的核心能力 | 登录、外呼、转接 |
| 业务场景 | 使用场景 | 预览外呼 + 软电话 |
| 参数配置 | 已知配置参数 | tenantId、agentNo |
| 特殊要求 | 额外约束 | 深色主题、移动端适配 |
基础描述:
请实现一个座席工作台页面,包含以下功能:
1. 登录/登出
2. 座席状态展示与切换
3. 预览外呼
4. 软电话接听/挂断
详细描述:
请实现一个座席工作台页面:
[功能需求]
- 登录:接收 sessionKey 参数
- 状态:展示当前座席状态,支持忙碌/空闲切换
- 外呼:预览外呼,支持输入客户号码
- 通话:软电话模式,支持接听、挂断、保持
- 转接:咨询转接、盲转、转 IVR
- 班长:监听、耳语、强插、代接
[UI 要求]
- 现代简洁风格
- 按 Tab 组织功能
- 通话面板居中展示
[参数配置]
- baseURL: https://agent-gateway.xxx.cn
- tenantId: 6000001
- endpointType: 3(软电话)
按模块描述:
请按模块实现座席工作台:
模块 1:登录模块
- 输入参数:tenantId、agentNo、sessionKey
- 展示当前状态
- 提供忙碌/空闲按钮
模块 2:外呼模块
- 输入框:客户号码
- 发起/取消外呼
- 展示外呼状态(拨号中/振铃中/已接通)
模块 3:通话模块
- 通话面板:展示号码、时长
- 操作按钮:接听、挂断、保持、静音
模块 4:班长模块
- 输入框:目标座席工号
- 操作:监听、耳语、强插、代接
写需求时先给整体框架,再写各模块;给出必须遵守的业务规则和明确配置值。
3.3 审阅生成代码
| 检查项 | 说明 |
|---|---|
| 功能完整性 | 是否覆盖了所有需求 |
| 参数正确性 | 配置参数是否与 API 文档一致 |
| 逻辑正确性 | 业务流程是否与时序一致 |
| 代码规范 | 是否符合团队规范 |
需要调整时,直接描述增量,例如:
请增加以下功能:
- 增加满意度调查按钮
- 增加外呼客户振铃状态展示
客户挂断后,通话面板没有隐藏。请修复这个问题。
请调整 UI 样式:
- 使用深色主题
- 将通话按钮改为圆形
- 默认折叠日志面板
请修正术语:
- 将 "set busy" 改为 "mark busy"
- 将 "pickup" 改为 "intercept"
可以分轮推进:先出页面框架,再补业务功能,再改样式,最后核对异常和断线。
上线前至少验证:
| 验证项 | 方法 |
|---|---|
| 登录流程 | 使用有效的 sessionKey 测试 |
| 外呼流程 | 发起外呼,检查状态变化 |
| 事件接收 | 检查日志面板是否记录 agentStatus、振铃、桥接 |
| 异常处理 | 模拟网络断开,确认重连或重新登录提示 |
四、代码示例
4.1 初始化
// 引入 SDK
<script src="https://your-cdn/agent-sdk.umd.js"></script>
// 获取 SDK 对象
const AgentSDK = window.AgentSDK.default || window.AgentSDK;
// 初始化配置
AgentSDK.setup({
baseURL: 'https://agent-gateway.example.com',
debug: false,
webrtc: true,
webrtcStats: false
});4.2 登录
async function login(sessionKey) {
const res = await AgentSDK.login({
tenantId: 'your-tenant-id',
agentNo: 'your-agent-no',
sessionKey: sessionKey,
bindEndpoint: {
endpointType: 3, // 3 = 软电话
endpoint: '1883'
},
initialStatus: 1 // 1 = 空闲
});
return res.code === 0;
}4.3 事件订阅
const { EventType } = AgentSDK;
// 座席状态
AgentSDK.on(EventType.AGENT_STATUS, (e) => {
console.log('状态:', e.status.state, e.status.stateAction);
});
// 外呼事件
AgentSDK.on(EventType.PREVIEW_OBCALL_RINGING, (e) => {
console.log('客户振铃中:', e.customerNumber);
});
AgentSDK.on(EventType.PREVIEW_OBCALL_BRIDGE, (e) => {
console.log('已接通');
});
// 重连通知
AgentSDK.on(EventType.RECONNECT_ATTEMPT, (e) => {
console.log('重连中:', e.attempt, '/', e.maxAttempts);
});4.4 外呼与通话控制
// 发起外呼
await AgentSDK.previewObCall({
customerNumber: '13800138000',
agentAnswerTimeout: 30,
customerAnswerTimeout: 45
});
// 接听(软电话)
await AgentSDK.sipLink();
// 挂断
await AgentSDK.sipUnlink();
// 保持
await AgentSDK.hold();4.5 置忙 / 置闲
// 置忙
await AgentSDK.pause({
pauseType: 1,
pauseDescription: 'MEETING'
});
// 置闲
await AgentSDK.unpause();4.6 同时处理两类失败
try {
const res = await AgentSDK.previewObCall(params);
// 服务端业务失败
if (res.code !== 0) {
console.error('操作失败:', res.message, res.errorCode);
return;
}
// 成功
console.log('操作成功');
} catch (err) {
// SDK 本地错误
if (err?.name === 'AgentSdkError') {
console.error('SDK 错误:', err.code, err.message);
}
}用 state 和 stateAction 驱动界面:
AgentSDK.on(EventType.AGENT_STATUS, (e) => {
const { state, stateAction } = e.status;
// 更新 UI
updateStatusBadge(state);
updateStatusText(stateAction);
updateButtonState(state);
});重连超过次数后提示重新登录:
AgentSDK.on(EventType.RECONNECT_ATTEMPT, (e) => {
if (e.attempt >= e.maxAttempts) {
// 超过最大重连次数
alert('连接已断开,请重新登录');
logout();
}
});配置集中存放:
const CONFIG = {
baseURL: 'https://agent-gateway.example.com',
tenantId: '6000001',
agentNo: '1865',
endpointType: 3,
endpoint: '1883'
};五、操作索引
方法签名和全部参数以 API(操作) 为准。
| 操作 | 说明 |
|---|---|
setup(config) | SDK 初始化 |
login(params) | 登录 |
logout(params) | 登出 |
pause(params) | 置忙 |
unpause() | 置闲 |
previewObCall(params) | 预览外呼 |
cancelPreviewObCall() | 取消外呼 |
sipLink() | 软电话接听 |
sipUnlink() | 软电话挂断 |
hold() | 保持 |
unhold() | 取消保持 |
mute(params) | 静音 |
unmute(params) | 取消静音 |
startAtxfer(params) | 发起咨询 |
cancelAtxfer() | 取消咨询 |
completeAtxfer() | 完成转接 |
threewayAtxfer() | 发起三方 |
blxfer(params) | 盲转 |
spy(params) | 监听 |
unspy() | 结束监听 |
whisper(params) | 耳语 |
unWhisper() | 结束耳语 |
barge(params) | 强插 |
六、附录
6.1 座席状态
| 状态 | 说明 |
|---|---|
| offline | 离线 |
| idle | 空闲 |
| busy | 忙碌 |
| ringing | 振铃 |
| talking | 通话中 |
| wrapup | 话后整理 |
完整 state / stateAction 见 状态机:状态/状态转移。
6.2 终端类型
| 类型值 | 说明 |
|---|---|
| 1 | PSTN 电话 |
| 2 | 分机 |
| 3 | 软电话(WebRTC) |
6.3 相关文档
Updated about 2 months ago
Did this page help you?