介绍

智能客服用户端的微信小程序 UIKit。使用此 UIKit，您可以在一天内将智能客服的能力集成到您的小程序项目。极简接入，用智能客服为您的产品增收提效，提升用户满意度和付费转化。

效果展示

开发环境要求

• 微信开发者工具

• JavaScript 或 TypeScript

• node（node.js ≥ 16.0.0）

• npm（版本请与 node 版本匹配）

UIKit 源码集成

步骤1：创建项目

在微信开发者工具上创建一个使用 JS-基础模板的小程序项目（是否使用模板，是否使用 TS 均可），如图所示：

步骤2：下载 UIKit

微信开发者工具创建的小程序项目默认没有 package.json，因此您需要先创建 package.json 文件。

npm init -y

通过 NPM 方式下载 UIKit。

npm i @tencentcloud/ai-desk-customer-wechat@latest

为了方便您对 UI 进行扩展，请在项目的根目录下执行以下命令，将 UIKit 源码复制到项目中。

【macOS 端】

mkdir -p ./ai-desk-customer-wechat && 
rsync -av --exclude={'node_modules','excluded-list.txt'} ./node_modules/@tencentcloud/ai-desk-customer-wechat/ ai-desk-customer-wechat/

【Windows 端】

robocopy .\node_modules\@tencentcloud\ai-desk-customer-wechat .\ai-desk-customer-wechat /E

步骤3：分包引入 UIKit

为了规避小程序主包体积超限问题，我们建议您将客服 UIKit 放入分包。

1. 工程配置

【app.js】

说明：

以下代码使用了分包异步化的技术方案。

"use strict";
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
let common_vendor;
require.async('./ai-desk-customer-wechat/common/vendor').then((res) => {
    common_vendor = res;
    const _sfc_main = {
        onLaunch: function() {
          console.log("App Launch");
        },
        onShow: function() {
          console.log("App Show");
        },
        onHide: function() {
          console.log("App Hide");
        }
      };
      function createApp() {
        const app = common_vendor.createSSRApp(_sfc_main);
        return {
          app
        };
      }
      createApp().app.mount("#app");
      exports.createApp = createApp;
}).catch(({ errMsg, mod }) => {
    console.error(`path: ${mod}, ${errMsg}`)
});

【app.json】

说明：

请务必配置 subPackages和 preloadRule。

{
  "pages": [
    "pages/index/index"
  ],
  "subPackages": [
    {
      "root": "ai-desk-customer-wechat",
      "pages": [
        "pages/index/index"
      ],
      "entry": "index.js"
    }
  ],
  "preloadRule": {
    "ai-desk-customer-wechat/pages/index/index": {
      "network": "all",
      "packages": [
        "ai-desk-customer-wechat"
      ]
    }
  },
  "window": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "Weixin",
    "navigationBarBackgroundColor": "#ffffff"
  },
  "style": "v2",
  "componentFramework": "glass-easel",
  "sitemapLocation": "sitemap.json"
}

2. 在项目主包页面中配置智能客服的入口

【主包 pages/index/index.js】

Page({
  data: {
  },
  getSupport() {
    // SDKAppID/userID/userSig 的获取请参考步骤4
    const SDKAppID = 0;
    const userID = '';
    const userSig = '';
    wx.navigateTo({
      url: `/ai-desk-customer-wechat/pages/index/index?SDKAppID=${SDKAppID}&userID=${userID}&userSig=${userSig}`
    })
  },
})

【主包 pages/index/index.wxml】

<button class="get-support" bind:tap="getSupport">咨询客服</button>

【主包 pages/index/index.wxss】

page {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.get-support {
  background-color: #0052d9;
  color: #ffffff;
  margin: auto;
}

步骤4：获取 SDKAppID 、userID 、 userSig

设置pages/index/index.js中的 SDKAppID、userID、userSig 。

• SDKAppID 信息，可在 即时通信 IM 控制台 单击应用管理 > 创建新应用，并选择智能客服 Desk ， 开通智能客服 后获取。

  

  

• userID 信息，可本地生成一个随机的字符串，例如 test-1234。

• userSig 信息，可单击 即时通信 IM 控制台 > UserSig生成校验，填写创建的 userID，即可生成 userSig。

  

步骤5：启动项目，并发起您的第一条客服咨询

测试前，请先清理微信开发者工具的缓存，并勾选本地设置 > 不校验合法域名。

高级特性

用户端带昵称和头像登录

如果您希望人工客服在工作台接待用户咨询时，能看到用户的昵称、头像等信息以提升沟通效率，效果如下所示：

修改主包 pages/index/index.js，设置 nickName 和 avatar 并将其传递给客服组件。

Page({
  data: {
  },
  getSupport() {
    // SDKAppID/userID/userSig 的获取请参考步骤4
    const SDKAppID = 0;
    const userID = '';
    const userSig = '';
    const nickName = ''; // 用户昵称
    const avatar = ''; // 用户头像
    wx.navigateTo({
      url: `/ai-desk-customer-wechat/pages/index/index?SDKAppID=${SDKAppID}&userID=${userID}&userSig=${userSig}`
        + `&nickName=${nickName}`
        + `&avatar=${avatar}`
    });
  },
})

工具栏快捷按钮

如果您想实现输入框上方增加快捷按钮方便用户使用，例如增加“人工客服”，“查询包裹”等，效果如下所示：

修改主包 pages/index/index.js，设置 toolbarButtonList 并将其转成 json 字符串后传递给客服组件。toolbarButtonList 是一个包含了一个或多个配置的数组，配置的描述如下：

Page({
  data: {
  },
  getSupport() {
    // SDKAppID/userID/userSig 的获取请参考步骤4
    const SDKAppID = 0;
    const userID = '';
    const userSig = '';
    const toolbarButtonList = [
      {"title":"人工服务","icon":"https://tccc-im-agent-avatar-1258344699.cos.ap-nanjing.myqcloud.com/toolbar_button_1.png","type":1,"content":"","isPreset":1,"presetId":"humanService","isEnabled":1},
      {"title":"服务评价","icon":"https://tccc-im-agent-avatar-sg-1258344699.cos.ap-singapore.myqcloud.com/toolbar_button_2.png","type":1,"content":"","isPreset":1,"presetId":"serviceRating","isEnabled":1},
      {"title":"结束对话","icon":"https://tccc-im-agent-avatar-sg-1258344699.cos.ap-singapore.myqcloud.com/toolbar_button_3.png","type":1,"content":"","isPreset":1,"presetId":"endHumanService","isEnabled":1},
      {"title":"智能客服","type":1,"content":"智能客服高","isPreset":0,"isEnabled":1}
    ];
    wx.navigateTo({
      url: `/ai-desk-customer-wechat/pages/index/index?SDKAppID=${SDKAppID}&userID=${userID}&userSig=${userSig}`
        + `&toolbarButtonList=${JSON.stringify(toolbarButtonList)}`
    });
  },
})

底部快捷订单

说明：

请升级 ai-desk-customer-wechat 到 v1.5.2 或更高版本。

如果您想实现打开客服会话时在聊天区域底部展示快捷订单，可以配置 bottomQuickOrder，效果如下所示：

修改主包 pages/index/index.js，设置 bottomQuickOrder 并将其转成 json 字符串后传递给客服组件。

bottomQuickOrder 的参数描述如下：

Page({
  data: {
  },
  getSupport() {
    // SDKAppID/userID/userSig 的获取请参考步骤4
    const SDKAppID = 0;
    const userID = '';
    const userSig = '';
    const toolbarButtonList = [
      {"title":"人工服务","icon":"https://tccc-im-agent-avatar-1258344699.cos.ap-nanjing.myqcloud.com/toolbar_button_1.png","type":1,"content":"","isPreset":1,"presetId":"humanService","isEnabled":1},
      {"title":"服务评价","icon":"https://tccc-im-agent-avatar-sg-1258344699.cos.ap-singapore.myqcloud.com/toolbar_button_2.png","type":1,"content":"","isPreset":1,"presetId":"serviceRating","isEnabled":1},
      {"title":"结束对话","icon":"https://tccc-im-agent-avatar-sg-1258344699.cos.ap-singapore.myqcloud.com/toolbar_button_3.png","type":1,"content":"","isPreset":1,"presetId":"endHumanService","isEnabled":1},
      {"type":1,"title":"智能客服高级版","content":"智能客服高级版","isPreset":0,"isEnabled":1}
    ];
    const bottomQuickOrder = {
      header: "智能客服高级版",
      desc: "¥3000/月",
      pic: "https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg",
      url: 'https://cloud.tencent.com/document/product/269/97537',
      customField: [
        {
          name: '订单号',
          value: '11111111111111111111'
        },
        {
          name: '下单时间',
          value: '2025-07-02 16:23'
        }
      ]
    };
    wx.navigateTo({
      url: `/ai-desk-customer-wechat/pages/index/index?SDKAppID=${SDKAppID}&userID=${userID}&userSig=${userSig}`
        + `&toolbarButtonList=${JSON.stringify(toolbarButtonList)}`
        + `&bottomQuickOrder=${JSON.stringify(bottomQuickOrder)}`
    });
  },
})

多客服号

说明：

请升级 ai-desk-customer-wechat 到 v1.5.3 或更高版本。

如果您的应用内需要多个客服号，为用户提供专属客服功能，以提高服务质量和响应速度，可用 UIKit 提供的多客服号功能实现。效果如下所示：

修改主包 pages/index/index.js，设置 customerServiceIDList 和 customerServiceID 并将其转成 json 字符串后传递给客服组件。

// 1. 初始化前将业务侧自定义的客服号 ID 传递给 UIKit
// 自定义客服号请使用 restapi - https://cloud.tencent.com/document/product/269/111798
const customerServiceIDList = ['customerServiceID_001', 'customerServiceID_002', 'customerServiceID_003'];
// 2. 初始化时，带上要发起会话的客服号 ID，比如 'customerServiceID_002'
// 如果不带上要发起会话的客服号 ID，则 UIKit 默认使用客服号 ID 列表的第 1 个元素
wx.navigateTo({
  url: `/ai-desk-customer-wechat/pages/index/index?SDKAppID=${SDKAppID}&userID=${userID}&userSig=${userSig}`
    + `&customerServiceIDList=${JSON.stringify(customerServiceIDList)}`
    + `&customerServiceID=customerServiceID_002`
});

常见问题

什么是 UserSig？如何生成 UserSig？

UserSig 是用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文。

UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端，并提供面向项目的接口，在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。

小程序如果需要上线或者部署正式环境怎么办？

请在 微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名中进行域名配置。域名配置详细参见：小程序合法域名。

交流与反馈

点此进入 IM 社群，享有专业工程师的支持，解决您的难题。