服务端 SDK

快速阅读

服务端 SDK 用来让企业自己的服务端在通话进行中控制座席：上线、置忙置闲、预览外呼、挂机、转接、咨询、保持等。它走 OpenAPI 座席动作（实施联调可用 Zenava CLI），不是浏览器里的 AgentSDK，也不是事件回调。

• 先准备 region、企业或部门标识、部门 token，按鉴权认证签名；时间戳约 30 分钟有效。
• 座席要先存在且绑定电话可用，再上线；绑定类型选分机时，分机必须已经注册成功。
• 接口返回成功只表示动作被受理。电话有没有响、有没有接通，要看绑定设备、Webhook 和话单。
• 服务端上线不要用软电话绑定来打电话；软电话和浏览器事件走座席工作台集成。
• 收事件走 Webhooks：事件回调；管座席工号、分机本身走 呼叫中心管理集成。

阅读地图

• 先分清和 AgentSDK、Webhook、管理集成的边界：读“二”和“九”。
• 要配鉴权、绑定和上线：读“六”。
• 要看动作分组：读“五”。
• 要验收：读“八”和“附录 C”。

一、文档说明

客户把呼叫能力嵌进 CRM 或自建中台时，经常是后端发起一次外呼、挂机或转接，页面上没有座席工作台。本文说明这条服务端控制怎么定位、先配什么、何时真正改到通话、失败怎么看。

适用：对接 CRM / 工单 / 自建中台的技术负责人、实施顾问、需要用命令行联调座席动作的运营管理员。

逐接口参数、签名算法和命令开关建议结合 鉴权认证、Zenava CLI 产品说明 一起确认。

二、产品总览

服务端 SDK 的对象是某一个已上线座席的实时会话，不是座席配置本身，也不是已经打完的话单。

企业后端签一次名，对指定座席工号发上线、外呼、挂机、转接；话机或分机负责响铃和通话，Webhook 负责把过程推回企业系统。

页面名叫 SDK，落地是同一套座席动作 OpenAPI；没有单独再下一套浏览器 npm 包。业务系统可以直接调接口，也可以用 Zenava CLI 包一层做联调。

三、核心概念

四、对象关系与运行链路

管理端先备好：座席工号、绑定电话 / 分机、技能组与队列
        ↓
企业服务端：region + 企业或部门 + token → 签名
        ↓
上线（绑定电话、绑定类型、置闲 / 置忙）
        ↓
座席动作：预览外呼 / 接听控制 / 保持 / 转接 / 咨询 / 挂机 …
        ↓
绑定设备响铃、接通
        ↓
Webhook 回写过程事件 → 主话单 / 从话单沉淀

四个层次不要混：

改绑定或下线，对之后的动作生效。已经打完的那一通不会被事后改队列、改绑定而改写话单。

五、能力地图

实际能调哪些动作，以企业开通能力和接口权限为准。常见分组如下。

通道变量可在外呼时带上，供后续推送、话单自定义字段或 SIP 头使用。逐参数不要在本页展开，以当前 OpenAPI 和 CLI 帮助为准。

六、配置项与生效

1. 配置来源与优先级

浏览器 AgentSDK 登录用的 sessionKey 不能代替本页签名。管理集成那把接口密钥管的是配置对象，也不等于座席已上线。

另有一条“座席服务端登录鉴权”，用来换 WebSocket 用的短时 sessionKey（约 30 秒）。它不是上线命令。服务端架构里过程事件更常见的是配 Webhook，不要和上线、外呼混成一步。

2. 鉴权与调用

配错表现：签名失败、无权限、打到另一套环境。先看 API 请求日志里的企业和 URI。

3. 上线与绑定

配错表现：上线成功但外呼报分机未注册、座席不在线、座席忙；或绑定了软电话类型，接口成功却无法呼叫。

4. 动作受理与通话结果

result 成功只说明平台收下了这条动作。客户未接、座席侧超时、名单拦截，要到 Webhook 和话单里看。

七、典型业务场景

• CRM 点号外呼：座席已上线，后端对当前座席工号发预览外呼，座席话机先响，再打客户。
• 工单页挂机：会话还在时用座席工号或 uniqueId 挂机，再用主话单核对结束原因。
• 后端转接：接通后转到队列或指定座席，Webhook 看转移 / 咨询接通。
• IP 话机座席：分机注册成功后上线，服务端只发动作，媒体在话机上。
• 与弹屏配合：外呼或响铃走 Webhook 打开资料，控制仍在本页。

八、上线准备与运营建议

1. 测试租户先做通：签名、查座席、上线、再查座席状态。
2. 绑定用普通电话或已注册分机，不要在本页用软电话类型验收外呼。
3. 选一个闭环：上线 → 预览外呼 → 挂机 → 话单和 Webhook 对上 uniqueId。
4. 生产按系统拆权限，外呼、挂机、转接不要和全量管理密钥绑在一把。
5. 动作失败先看返回说明：座席不在线、忙、无外呼权限、分机未注册、名单拦截。
6. 实施联调用 Zenava CLI 的 callcenter agent 系列；正式业务系统直接调 OpenAPI。

九、与周边能力的关系

十、FAQ

和 AgentSDK 登录是一回事吗？
不是。AgentSDK 在浏览器里用 sessionKey 登录工作台；本页用企业 / 部门 token 签名，从服务端发动作。

上线成功为什么还是外呼失败？
常见是分机未注册、绑定了软电话类型、座席忙、没有外呼权限，或号码被名单拦住。回查绑定和座席状态，不要只看上线返回。

接口成功，客户没响铃？
动作被受理不等于客户侧已振铃。核座席侧设备、外呼超时和 Webhook 响铃事件。

能不能靠本页收响铃事件？
不能。收通知走 Webhook；本页只发控制。

服务端登录鉴权是不是上线？
不是。那条用来换短时 WebSocket 凭证。上线是单独的座席动作。

十一、总结

先签通、再上线、再发一个外呼或挂机，用设备和话单确认这一通真的变了。服务端 SDK 解决的是企业后端怎么控座席会话，不替代工作台软电话，也不替代话单。

附录 A：入口与权限

附录 B：关键字段口径

附录 C：实施检查清单

• region、企业或部门、token 与目标租户一致
• 测试签名能通过（失败先对照鉴权认证）
• 座席已创建，绑定电话或分机可用；分机已注册
• 上线后座席状态为置闲或预期的置忙
• 未使用软电话绑定类型做服务端外呼验收
• 预览外呼或挂机返回受理成功
• Webhook 或话单能用 uniqueId / mainUniqueId 对上这一通
• 座席不在线、忙、分机未注册、名单拦截能从返回或日志对上
• 生产权限只开本系统需要的座席动作

附录 D：常见问题速查