开发者文档中心

OpenAPI进入控制台

微信小程序 SDK · 2026-10-31

与微信原生客服按钮的区别

原生 SDK 和 open-type="contact" 是两条独立链路。

微信客服消息接入:按角色完成配置

  1. 开发者在自己的小程序中添加 open-type="contact" 按钮;已有按钮可以复用。先提交体验版,不用把管理端网址嵌入页面。
  2. 小程序管理员在云蝠的小程序连接器中填写 AppID、AppSecret,绑定已发布智能体并保存。当前是密钥接入;未提供第三方平台扫码授权。
  3. 复制本连接专用的公网 HTTPS 消息推送 URL。在微信后台配置同一 Token 与 EncodingAESKey,选择安全模式和 XML;先在云蝠保存密钥,再提交微信的 URL 验证。
  4. 让接待组客服登录并切换在线。测试人员从体验版进入原生客服窗口,发送一条文本;只打开窗口不能证明消息接入成功。
  5. 核对连接入站记录、接待台消息及手机实际回复。能接收但不能发送时,再排查稳定 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 分流未接通

微信原生客服的消息路径

  1. 用户点击客服

    小程序的 contact 按钮打开微信客服窗口。

  2. 微信推送消息

    公网回调验签、解密,校验 AppID 并去重。

  3. 云蝠处理会话

    绑定智能体接待,或由有权限的人工客服接管。

  4. 回复回到微信

    调用平台发送接口,再核对手机实际收到的文本。

原生客服接入检查

  1. 管理员取得本小程序 AppID、AppSecret,确认客服消息权限;开发者在小程序放置 open-type="contact" 按钮。当前采用密钥接入。
  2. 先准备回调 Token,并在微信消息推送设置中生成 EncodingAESKey。在云蝠对应小程序连接器中填写 AppID、AppSecret、Token、EncodingAESKey,绑定已发布智能体并保存连接;密钥只保存在服务端。
  3. 复制已保存连接专属的公网 HTTPS 回调地址,填入微信消息推送配置;核对两端 Token 与 EncodingAESKey 一致,选择安全模式与 XML 后提交。不要替换其他在用应用的回调。
  4. 完成平台 URL 校验与凭据检查,再用体验版或正式版发送真实文本。分别核对入站记录、平台发送结果和手机收到的回复。
  5. 如需人工接待,先在接待台将至少一个客服账号设为在线,再验证转接、接管和人工回复。记录发送权限及窗口限制;握手成功不是完整收发成功。

最小客服入口

运行前

页面 WXML 片段 · 界面片段 · 接入包 0.3.14

  • 管理员先配置独立的微信小程序客服消息连接器并启用微信客服能力。
完整代码 · 4 行
页面 WXML 片段XML
<!-- The bound WeChat mini-program must enable its customer-service callback. -->
<navigator url="/pages/hosted-support/index?native=1">微信客服</navigator>
<!-- Direct consultation stays available without sharing profile information. -->
<button open-type="contact">直接咨询</button>
使用流程预览 · 示意图

帮助理解此示例的使用顺序,不执行代码或验证连接。

  1. 准备

    管理员先配置独立的微信小程序客服消息连接器并启用微信客服能力。

  2. 在项目中使用

    页面 WXML 片段 · 界面片段

  3. 核对结果

    点击打开微信控制的客服窗口,不会打开 SDK 聊天、实时语音或套用渠道皮肤。

预期结果:点击打开微信控制的客服窗口,不会打开 SDK 聊天、实时语音或套用渠道皮肤。

卡在哪一步,先检查什么

现象优先检查
URL 校验失败公网 HTTPS 可达;URL 对应当前连接;两端 Token、EncodingAESKey、AppID 一致
校验通过但没有客户消息发送的是否为当前 AppID 的文本;消息推送是否启用;云蝠连接与入口是否可用
消息入站但手机没有回复平台发送回执、凭据有效性、出口 IP 白名单和客服发送窗口;平台接受后仍需手机核对
转人工后一直等待服务时段、接待组、客服在线状态和实际接管记录;入队不代表已接管
CRM、指定客服或卡片参数不生效当前原生链路未接入 session-from 分流或卡片;不要将客户端字段作为可信身份
实现依据 · 仓库内路径
  • docs/WECHAT-MINIAPP-INTEGRATION.md
  • lib/developer-docs/integration-playbooks.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。