与微信原生客服按钮的区别
原生 SDK 和 open-type="contact" 是两条独立链路。
微信客服消息接入:按角色完成配置
- 开发者在自己的小程序中添加 open-type="contact" 按钮;已有按钮可以复用。先提交体验版,不用把管理端网址嵌入页面。
- 小程序管理员在云蝠的小程序连接器中填写 AppID、AppSecret,绑定已发布智能体并保存。当前是密钥接入;未提供第三方平台扫码授权。
- 复制本连接专用的公网 HTTPS 消息推送 URL。在微信后台配置同一 Token 与 EncodingAESKey,选择安全模式和 XML;先在云蝠保存密钥,再提交微信的 URL 验证。
- 让接待组客服登录并切换在线。测试人员从体验版进入原生客服窗口,发送一条文本;只打开窗口不能证明消息接入成功。
- 核对连接入站记录、接待台消息及手机实际回复。能接收但不能发送时,再排查稳定 access_token、权限、回复时限与发送失败记录。
按失败阶段定位
| 现象 | 先检查哪里 | 通过标准 |
|---|---|---|
| URL 验证不通过 | 公网 HTTPS、专用回调 URL、相同 Token/AES Key、安全模式与 XML | 微信后台验证通过,凭据不出现在小程序代码里 |
| 点按钮后没有会话 | 按钮是否 open-type="contact";是否真正发送文本;连接是否启用 | 云蝠收到同一小程序的文本入站记录 |
| 有入站,没有回复 | 智能体已发布、在线接待、官方权限及发送失败记录 | 手机实际收到对应回复 |
| 回复偶发失效 | 服务端稳定 access_token 的使用方式,避免其他系统强制刷新 | 检查发送结果后恢复收发,不盲目重发 |
先确定客户在哪里聊天
希望客服界面留在自己的小程序页面内,选择源码组件。希望进入微信原生客服窗口,选择原生客服消息连接器。两种方式都需要各自的配置与验收。
选择哪一种
| 项目 | 云蝠源码 SDK | 微信原生客服消息 |
|---|---|---|
| 界面 | 小程序内的 yunfu-chat 组件 | 微信原生客服窗口 |
| 渠道 | 独立自建 Web 入口 | 对应微信小程序连接器 |
| 凭据 | 公开 key / entryId + 访客 Bearer | 服务端 AppID / AppSecret / Token,安全模式 AES Key |
| 网络 | HTTPS request / upload / download | 平台回调和官方发送接口 |
| 边界 | 非已上架插件,无 openid 认证 | 当前文本与加密 XML;扫码授权、卡片和 session-from 分流未接通 |
微信原生客服的消息路径
- 用户点击客服
小程序的 contact 按钮打开微信客服窗口。
- 微信推送消息
公网回调验签、解密,校验 AppID 并去重。
- 云蝠处理会话
绑定智能体接待,或由有权限的人工客服接管。
- 回复回到微信
调用平台发送接口,再核对手机实际收到的文本。
原生客服接入检查
- 管理员取得本小程序 AppID、AppSecret,确认客服消息权限;开发者在小程序放置 open-type="contact" 按钮。当前采用密钥接入。
- 先准备回调 Token,并在微信消息推送设置中生成 EncodingAESKey。在云蝠对应小程序连接器中填写 AppID、AppSecret、Token、EncodingAESKey,绑定已发布智能体并保存连接;密钥只保存在服务端。
- 复制已保存连接专属的公网 HTTPS 回调地址,填入微信消息推送配置;核对两端 Token 与 EncodingAESKey 一致,选择安全模式与 XML 后提交。不要替换其他在用应用的回调。
- 完成平台 URL 校验与凭据检查,再用体验版或正式版发送真实文本。分别核对入站记录、平台发送结果和手机收到的回复。
- 如需人工接待,先在接待台将至少一个客服账号设为在线,再验证转接、接管和人工回复。记录发送权限及窗口限制;握手成功不是完整收发成功。
卡在哪一步,先检查什么
| 现象 | 优先检查 |
|---|---|
| URL 校验失败 | 公网 HTTPS 可达;URL 对应当前连接;两端 Token、EncodingAESKey、AppID 一致 |
| 校验通过但没有客户消息 | 发送的是否为当前 AppID 的文本;消息推送是否启用;云蝠连接与入口是否可用 |
| 消息入站但手机没有回复 | 平台发送回执、凭据有效性、出口 IP 白名单和客服发送窗口;平台接受后仍需手机核对 |
| 转人工后一直等待 | 服务时段、接待组、客服在线状态和实际接管记录;入队不代表已接管 |
| CRM、指定客服或卡片参数不生效 | 当前原生链路未接入 session-from 分流或卡片;不要将客户端字段作为可信身份 |
实现依据 · 仓库内路径
docs/WECHAT-MINIAPP-INTEGRATION.mdlib/developer-docs/integration-playbooks.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。