小程序对讲开发指南
本文面向要在自己的微信小程序中集成云对讲能力的客户开发者：坐席在客户自己的小程序里登录、上班、接听设备来电、主动呼叫设备。
如果不需要自定义 UI，直接使用臻云提供的「臻识运维小助手」小程序即可，参见使用指南第五步，无需本文。
整体方案
客户小程序作为坐席端接入：
客户小程序（坐席登录/上班/呼叫）
│ ① AccessKey 签名（公司身份）+ X-Agent-Token（坐席身份）
▼
臻云开放平台 /openapi/v1/voip/*（本目录 6 个接口）
│
▼
臻云 VoIP 服务（呼叫中心/语音桥接）
▲
│ ② 微信硬件 VoIP 通道（来电唤醒/建房）
微信服务器 ⇄ 客户适配器（wcs，收微信回调）⇄ 臻云平台
前提条件
- 微信硬件 VoIP 资质（周期最长，最先启动）：企业主体认证 + 终端合作平台 + 设备认证 + 自有
model_id，设备 SN 在微信平台绑到客户小程序的 model 下。 - 客户适配器（wcs）：持客户微信凭据的独立服务（臻云提供开源工程），负责取
sn_ticket/openId与接收微信回调。部署与配置说明随工程交付。 - AccessKey：在臻云控制台创建，
allowed_apis勾选本目录 6 个接口（api id 90-95）。 - wmpf-voip 插件：小程序后台申请使用资格，
manifest.json声明（version 锁定，providerwxf830863afde621eb）。 - 坐席分机：管理员在臻云控制台创建（参见使用指南第一步），并把坐席的「绑定小程序」配成客户小程序。
参考实现（开源示例下载）
两条链路各有一个可直接运行的示例工程，建议开发前先下载跑通，再按自身业务改造：
| 示例 | 下载 | 说明 |
|---|---|---|
| wcs 客户适配器 | wcs.zip | 服务端参考实现：持客户微信凭据，实现取 sn_ticket/openId 与接收微信回调（即前提条件 2 的「客户适配器」）。含部署与配置说明（README），可独立部署，也可作为自研服务端的功能对照 |
| 小程序示例（xcx-demo） | xcx-demo.zip | 小程序参考实现（原生微信小程序、零第三方依赖）：完整演示本文全部 6 个接口的调用闭环（登录/上下班/设备列表/授权/主动呼叫/接听），含 AccessKey 签名的纯 JS 实现（MD5/HMAC-SHA1）与 wmpf-voip 插件集成 |
两个示例配套使用构成完整链路：小程序示例负责坐席界面与开放平台调用，wcs 负责微信侧凭据与回调。仅使用臻识运维小助手小程序时无需部署 wcs。
双层鉴权模型
所有接口都需要两层身份：
| 层 | 凭据 | 定位 | 获取方式 |
|---|---|---|---|
| 第一层 | AccessKey 签名 | 哪家客户公司 | 签名认证（query 三参） |
| 第二层 | X-Agent-Token | 哪个坐席 | 坐席登录换发 |
X-Agent-Token 规则：
- 放在请求头
X-Agent-Token（不能用Authorization，网关会覆盖） - 7 天有效，过期或换 AccessKey 后需重新登录
- 除登录外的 5 个接口都必带
调用闭环
1. 坐席登录
wx.login() 拿 code → 调坐席登录（{uri: "分机号@域名", password, wx_code}）→ 得 token。首次登录自动把当前微信绑定到该坐席分机（一微信绑一坐席）。
2. 上班
调坐席上下班（{online: true}）。上线状态云端维系，小程序切后台/被回收不影响。
3. 授权设备（接听来电的前提）
微信安全机制要求坐席先授权设备才能被呼叫唤醒：
- 调获取建房凭据（
{sn}）→ 得{app_id, model_id, wxa_flavor, sn_ticket} - 调
wx.requestDeviceVoIP({ sn, modelId: model_id, snTicket: sn_ticket })完成授权
4. 接听来电
设备按键呼叫 → 呼叫中心分配坐席 → 该坐席所有在线端同时振铃 → 微信弹出原生来电界面，点击接听（先接先通）。无需调任何接口，微信通道自动完成。
5. 主动呼叫设备
- 调遍历可呼设备拿可呼列表（设备的「默认呼叫号码」需授权本坐席或其呼叫中心）
- 调主动呼叫设备（
{device_sn}）→ 得payload wmpfVoip.callDevice({ roomType: 'video', sn, modelId: 客户MODEL_ID, isCloud: true, payload, ... })建房呼设备
6. 下班
调坐席上下班（{online: false}）。
时序图
sequenceDiagram
participant MP as 客户小程序
participant OP as 臻云开放平台
participant WX as 微信
MP->>OP: 坐席登录(90) {uri,password,wx_code}
OP-->>MP: token（X-Agent-Token）
MP->>OP: 上班(92) {online:true}
MP->>OP: 获取建房凭据(95) {sn}
OP-->>MP: {app_id,model_id,wxa_flavor,sn_ticket}
MP->>WX: wx.requestDeviceVoIP({sn,modelId,snTicket})
Note over WX: 设备按键呼叫 → 分配坐席
WX-->>MP: 原生来电界面（振铃）
MP->>OP: 主动呼叫(94) {device_sn}
OP-->>MP: {allowed,payload,device}
MP->>WX: wmpfVoip.callDevice({payload,...})
常见问题
Q: 登录报「分机号或密码错误」但密码没错？ 检查：① 坐席的「绑定小程序」是否配成当前客户的 appid（配错会走错微信通道）；② AccessKey 所属公司是否与坐席所在公司一致（跨公司会被同文案拒绝，防枚举）。
Q: 登录报「该坐席未绑定客户小程序」？ 这些接口只服务绑定客户小程序的坐席。联系管理员在臻云控制台「坐席分机管理」把该坐席的「绑定小程序」配成贵司小程序（需先完成前提条件中的资质与配置）。未绑定的坐席属于臻识运维小助手模式，直接使用该小程序即可。
Q: 获取建房凭据报「该设备未绑定客户小程序」？ 同上——设备分机的「绑定小程序」未配成贵司小程序。联系管理员配置。
Q: 换了 AccessKey 后所有坐席都要重新登录？ 是。坐席凭证与 AccessKey 绑定（验签密钥即 AccessKey 密钥），换 AccessKey 后旧 token 全部失效，属预期行为。
Q: 401 认证错误？ ① AccessKey 签名错（expires 过期/签名算法错，参见签名认证）；② X-Agent-Token 缺失或过期（重新登录）。
Q: 通话记录在哪里看？ 臻云控制台「通话记录」页面（管理员）。