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 URLAgent 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 终端类型

类型值说明
1PSTN 电话
2分机
3软电话(WebRTC)

6.3 相关文档


Did this page help you?