开发者文档中心

OpenAPI进入控制台

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

小程序 SDK:安装与首条消息

默认通过 web-view 复用当前原版渠道页面;原生组件作为替代方案。

下载接入包

先选接入方式,再准备对应参数

客户在哪里聊天使用哪条链路需要准备什么
原版渠道页面(默认)pages/hosted-support/ 的 web-view具备 web-view 使用资格,配置业务域名、HTTPS 主机、公开 key 和 entryId
原生组件(主动选择)pages/support/ 的 yunfu-chat 组件配置 request / uploadFile / downloadFile 合法域名;同步基础外观,不等同于完整网页
微信原生客服窗口小程序客服消息连接器小程序管理员、服务端凭据及安全 XML 消息推送;不要填到 SDK 的 config.js

开发、管理员和客服各自要完成什么

负责人操作完成证据
开发者导入自己的 AppID,默认配置 web-view 业务域名与公开入口;原生方案另注册组件与服务器域名检查入口可读取;不把管理密钥放进小程序
企业管理员启用入口、发布智能体、配置接待组和服务时间入口与已发布版本匹配;需要人工时有在线坐席
测试人员与客服体验版真机发业务问题,接待台核对同一会话,再完成转人工手机有实际回复;两端消息、来源和人工接管状态一致

从下载到首条回复

  1. 准备入口与域名

    在自建渠道创建入口;默认方案配置微信业务域名。

  2. 导入示例并检查

    导入解压根目录,选择自己的 AppID,填写 config.js;保留 hosted-support 为首页。

  3. 点击“进入客服”

    同意宿主隐私说明后进入原版渠道,再发送测试问题。

  4. 核对两端结果

    手机看到回复,接待台找到对应记录;再测人工。

开始前准备这些信息

准备项在哪里取得 / 配置核对结果
小程序 AppID自己的微信小程序后台与开发者工具工程使用本企业 AppID;不把 AppSecret 放入小程序
baseUrl云蝠已部署的公网 HTTPS 站点只包含协议和主机,不带 /console 路径
公开 key、entryId本文“统一填写公开入口配置”可选择渠道查看;也可在渠道 → 自建渠道 → 服务入口 → 皮肤与代码取得属于同一入口;入口已启用、绑定智能体已发布
业务域名(默认原版方案)微信后台 web-view 业务域名配置具备 web-view 使用资格并完成域名校验;request 域名不能替代
服务器域名(仅原生替代)微信后台 request / uploadFile / downloadFile 配置原生组件请求使用;开发工具和真机均开启域名校验
接待组与在线客服渠道的接待设置与接待台需要人工接待时,组内至少一名客服在线

前置准备

  1. 准备自己的小程序 AppID 和开发者工具工程;创建独立自建 Web 入口,复制 HTTPS baseUrl、公开 key 和 entryId。
  2. 下载独立小程序 SDK,导入解压根目录的 project.config.json,选择自己的 AppID,填写 config.js。默认首页是 pages/hosted-support/index;已有工程合并 hosted 页面、yunfu-sdk/hosted.js 与公开配置,保留 require 的相对路径。
  3. 默认 web-view 必须将同一公网 HTTPS 主机配置为业务域名;仅在主动选择原生组件时使用 request、uploadFile、downloadFile 域名。两种域名不可替代,不关闭校验代替配置。
  4. 默认首页完成宿主隐私同意后点击进入客服,核对同一入口的当前外观。需要原生替代时点击原生组件接入示例,先检查服务入口,再聊一聊;下方组件注册与 SDK 动作仅适用于该替代方案。

原生替代:只读入口检查

运行前

yunfu-sdk/examples/preflight.js · CommonJS 模块 · 接入包 0.3.14

  • 复制整个 yunfu-sdk;传入 wx、baseUrl、key、entryId、userScope。
完整代码 · 15 行
yunfu-sdk/examples/preflight.jsJavaScript
const { YunfuMiniappClient, diagnoseMiniapp } = require('../index');

// options contains wx, baseUrl, key, entryId, userScope. This function never creates a visitor.
async function checkSupportEntry(options) {
  const local = diagnoseMiniapp(options);
  if (!local.localReady) return local;
  const client = new YunfuMiniappClient(options);
  try {
    await client.preflight();
    return { ...local, entryReachable: true };
  } finally {
    client.destroy();
  }
}
module.exports = { checkSupportEntry };
使用流程预览 · 示意图

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

  1. 准备

    复制整个 yunfu-sdk;传入 wx、baseUrl、key、entryId、userScope。

  2. 在项目中使用

    yunfu-sdk/examples/preflight.js · CommonJS 模块

  3. 核对结果

    调用 checkSupportEntry(options) 只检查本机配置和公开入口,不创建会话或调用 AI。

预期结果:调用 checkSupportEntry(options) 只检查本机配置和公开入口,不创建会话或调用 AI。

同步渠道聊天外观

默认 web-view 加载 /support?surface=channel,与网页渠道共用当前渲染,头像、标题、消息、输入区、语音入口及已启用功能随渠道更新;保存渠道后重新进入核对。原生 yunfu-chat 只同步基础皮肤与各自支持的功能,不承诺完整网页效果;完整复制 yunfu-sdk/,保留 presentation.js 与 assets/avatars/。

宿主 app.json 需要 darkmode: true;示例已附 theme.json,默认进入前页面适配系统明暗主题。仅原生替代方案预取公开外观并在点击聊一聊后创建会话。小程序原生客服窗口由微信绘制,无法套用此聊天皮肤。

iOS、Android、Harmony 与 Uniapp App 示例继续打开同一入口的 /support 页面,继承渠道聊天外观;Web 无 UI SDK 仅返回配置,宿主自绘界面需要自行映射,或使用现成嵌入组件。

隐私、登录与能力范围

宿主负责隐私保护指引和实际用户同意;默认 WebView 页的勾选框不替代宿主完整隐私授权。原生替代示例含 getPrivacySetting 与 agreePrivacyAuthorization 按钮,不覆盖全局隐私监听。getRandomValues 从基础库 2.15.0 提供且在微信插件中不支持,本交付采用源码组件。

userScope 只隔离本机会话,不认证会员;客户订单和跨设备历史需要独立服务端身份方案。原生 yunfu-voice 组件支持服务配置就绪后的实时语音;录音消息未提供。启用入口实时互动后,还须完成腾讯 TRTC、微信推拉流权限、隐私和真机验收。

统一填写公开入口配置

运行前

config.js · 配置文件 · 接入包 0.3.14

  • 将文件放在小程序工程根目录,替换公开入口值。
  • userScope 是本地隔离标识;账号切换时更换,不能用它认证微信会员。
完整代码 · 9 行
config.jsJavaScript
/* Replace these public entry values. Never paste AppSecret, session_key or admin API keys. */
module.exports = {
  baseUrl: 'https://support.example.com',
  testMode: false, // Enable explicitly for local testing; never for a release mini-program.
  publicKey: 'replace-with-public-key',
  entryId: 'replace-with-entry-id',
  userScope: 'guest', // Local partition only. Change on login/logout; not authenticated identity.
  visitorContext: { app: { name: '业务小程序', platform: 'wechat-miniapp', version: '1.0' } },
};
使用流程预览 · 示意图

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

  1. 准备

    将文件放在小程序工程根目录,替换公开入口值。 userScope 是本地隔离标识;账号切换时更换,不能用它认证微信会员。

  2. 在项目中使用

    config.js · 配置文件

  3. 核对结果

    页面与组件从同一 config.js 读取入口,密钥和 AppSecret 不进入前端。

预期结果:页面与组件从同一 config.js 读取入口,密钥和 AppSecret 不进入前端。

原生替代:页面 JSON

运行前

pages/support/index.json · 页面配置 · 接入包 0.3.14

  • 根目录已复制 yunfu-sdk,并在 app.json 注册 pages/support/index。
完整代码 · 3 行
pages/support/index.jsonJSON
{
  "usingComponents": { "yunfu-chat": "/yunfu-sdk/components/yunfu-chat/index" }
}
使用流程预览 · 示意图

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

  1. 准备

    根目录已复制 yunfu-sdk,并在 app.json 注册 pages/support/index。

  2. 在项目中使用

    pages/support/index.json · 页面配置

  3. 核对结果

    微信开发工具能解析 yunfu-chat 原生组件;不是微信插件声明。

预期结果:微信开发工具能解析 yunfu-chat 原生组件;不是微信插件声明。

原生替代:页面 WXML

运行前

pages/support/index.wxml · 页面文件 · 接入包 0.3.14

  • 与同包 index.js、index.wxss 和 config.js 一起复制。
完整代码 · 15 行
pages/support/index.wxmlXML
<view class="setup">
  <view class="title">接入检查</view>
  <view class="hint">先在开发者工具选择自己的 AppID,再填写根目录 config.js。此处检查不会创建会话或调用 AI。</view>
  <view wx:for="{{checks}}" wx:key="id" class="check"><text>{{item.status === 'pass' ? '✓' : item.status === 'fail' ? '待修正' : '需核对'}} · {{item.message}}</text></view>
  <button bindtap="checkSetup" loading="{{checking}}" disabled="{{checking || !localReady}}">检查服务入口</button>
  <view class="hint">{{connectionStatus}}</view>
  <view wx:if="{{errorCode}}">错误码:{{errorCode}}</view>
  <view wx:if="{{needPrivacy}}">
    <view>图片、视频和文件选择前,请先阅读本小程序的隐私保护指引。</view>
    <button bindtap="openPrivacy">查看{{privacyName}}</button>
    <button open-type="agreePrivacyAuthorization" bindagreeprivacyauthorization="onPrivacyAgreed">我已阅读并同意</button>
  </view>
  <view wx:if="{{serviceState}}">当前接待状态:{{serviceState}}</view>
</view>
<yunfu-chat test-mode="{{testMode}}" wx:if="{{ready}}" base-url="{{baseUrl}}" public-key="{{publicKey}}" entry-id="{{entryId}}" user-scope="{{userScope}}" visitor-context="{{visitorContext}}" bind:statechange="onStateChange" bind:error="onSdkError" />
聊天交互预览 · 本地示意

通用聊天交互示意,回复为固定演示内容;不执行此源码、不连接当前渠道或调用模型。

客户服务助手欢迎咨询

您好,我是您的服务助手。有什么可以帮您?

对应源码:pages/support/index.wxml。实际效果请在自己的宿主中按下方验收项核对。

预期结果:显示入口检查及宿主隐私流程;检查通过后显示渠道聊天组件,语音仍受服务端开关约束。

原生替代:页面逻辑与清理

运行前

pages/support/index.js · 页面文件 · 接入包 0.3.14

  • 使用上方同包 JSON/WXML,保留 ../../config 和 ../../yunfu-sdk 相对目录。
完整代码 · 60 行
pages/support/index.jsJavaScript
/* global Page, wx */
// Native miniapp modules use CommonJS without a bundling step.
const config = require('../../config');
const { YunfuMiniappClient, diagnoseMiniapp } = require('../../yunfu-sdk/index');

const setupHints = {
  WX_DOMAIN_NOT_ALLOWED: '请在微信后台将 baseUrl 的主机加入 request 合法域名,并保持域名校验开启。附件还需单独配置 uploadFile 和 downloadFile。',
  WX_TLS_FAILED: '请核对公网 HTTPS 证书链及有效期,再使用体验版真机检查。',
  WX_PRIVACY_REQUIRED: '请先按宿主规则完成隐私授权,再重新检查;不要关闭全局隐私保护。',
  NETWORK_TIMEOUT: '请求超时,请检查网络后重试入口检查。此检查只读,不会创建会话。',
  NETWORK_UNCERTAIN: '网络结果未确认,请恢复网络后重试入口检查,不要据此重复发送业务消息。',
  CHANNEL_UNAVAILABLE: '请核对同一入口的公开 key、entryId 与启用状态;不要填写 AppID 或管理 API Key。',
};
Page({
  data: { ...config, checking: false, localReady: false, checks: [], ready: false, connectionStatus: '', errorCode: '', serviceState: '', needPrivacy: false, privacyName: '小程序隐私保护指引' },
  onLoad() {
    const report = diagnoseMiniapp({ ...config, key: config.publicKey, wx });
    this.setData({ localReady: report.localReady, checks: report.checks });
    // Host-owned privacy UI; the SDK never replaces an app's global privacy listener.
    if (typeof wx.getPrivacySetting === 'function') wx.getPrivacySetting({
      success: result => this.setData({ needPrivacy: result.needAuthorization, privacyName: result.privacyContractName || '小程序隐私保护指引' }),
      fail: () => this.setData({ connectionStatus: '隐私设置未读取成功;附件使用前请按宿主规则核对。' }),
    });
  },
  async checkSetup() {
    if (this.data.checking || !this.data.localReady) return;
    const generation = (this.checkGeneration || 0) + 1;
    this.checkGeneration = generation;
    this.setData({ checking: true, connectionStatus: '', errorCode: '' });
    let client;
    try {
      client = new YunfuMiniappClient({ ...config, key: config.publicKey, userScope: 'setup-check', wx });
      this.checkClient = client;
      await client.preflight(); // GET only; no visitor token, conversation, model or human dispatch.
      if (generation === this.checkGeneration)
        this.setData({ ready: true, connectionStatus: '已读取服务入口。请点击“聊一聊”,发送问题并在接待台核对实际回复。' });
    } catch (error) {
      if (generation === this.checkGeneration) this.setData({ errorCode: error.code || 'REQUEST_FAILED', connectionStatus: setupHints[error.code] || '入口检查未通过。核对公开参数与服务端入口状态,再按 README 的错误码说明排查。' });
    } finally {
      if (client) client.destroy();
      if (generation === this.checkGeneration) { this.checkClient = null; this.setData({ checking: false }); }
    }
  },
  openPrivacy() {
    if (typeof wx.openPrivacyContract === 'function') wx.openPrivacyContract({ fail: () => this.setData({ errorCode: 'WX_PRIVACY_REQUIRED' }) });
  },
  onPrivacyAgreed() { this.setData({ needPrivacy: false }); },
  onStateChange(event) {
    this.setData({ serviceState: event.detail.connected ? event.detail.state : 'not-connected' });
  },
  onSdkError(event) {
    // These bounded codes contain no visitor token, request body or customer text.
    this.setData({ errorCode: event.detail.code });
  },
  onUnload() {
    this.checkGeneration = (this.checkGeneration || 0) + 1;
    if (this.checkClient) this.checkClient.destroy();
    this.checkClient = null;
  },
});
使用流程预览 · 示意图

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

  1. 准备

    使用上方同包 JSON/WXML,保留 ../../config 和 ../../yunfu-sdk 相对目录。

  2. 在项目中使用

    pages/support/index.js · 页面文件

  3. 核对结果

    用户点击只读检查后才能打开接待;卸载会取消旧检查并清理实例。

预期结果:用户点击只读检查后才能打开接待;卸载会取消旧检查并清理实例。

检查首次打开

默认页面先显示隐私确认与进入客服按钮;无法加载时核对 web-view 使用资格、业务域名、HTTPS 和公开入口。原生替代页面使用检查入口与聊一聊。open-type="contact" 是另一条微信原生客服链路,请按对应教程配置。

原生替代:常见阻塞与处理

错误码 / 情况先检查
WX_DOMAIN_NOT_ALLOWED对应 request / uploadFile / downloadFile 合法域名,不用关闭校验替代
WX_TLS_FAILED证书有效期、主机与信任链,分别验证 iOS / Android
WX_PRIVACY_REQUIRED / WX_MEDIA_PERMISSION_DENIED宿主隐私授权与相册/文件权限;取消选择不当成失败
NETWORK_TIMEOUT / NETWORK_UNCERTAIN先刷新对账,再重试原 operation;不自动换 ID 重发
首次没有转人工目标先发送客户诉求;需人工优先时在接待设置选择人工优先,忙时排队;未发首句直接 handoff 尚未提供

原生替代:怎样确认接入成功

操作小程序中应看到云蝠中应看到
发送业务问题实际 AI 回答,而非示例或初始化成功提示同一入口的客户消息与 AI 回复
请求转人工等待状态;接管后显示人工回复进入正确的接待队列,客服接管后 AI 停止外发
取消选择文件,再选择并发送取消不报成功;发送后可以预览同一会话内的附件记录,其他访客不可读取
退出账号 A,再登录 B不展示 A 的历史或未完成请求分别使用隔离会话;userScope 不作为身份认证
断网后恢复保留待核对请求,刷新后决定是否重试不因重试产生重复消息或重复业务操作

官方原始接入文档

先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。

实现依据 · 仓库内路径
  • sdk/wechat-miniapp/README.md
  • sdk/wechat-miniapp/example/pages/support/index.wxml
  • docs/MINIAPP-FIRST-CUSTOMER.md

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