小程序接入在线客服

小程序接入在线客服分为两种方式：1.小程序原生接入。 2.小程序sdk接入

1.小程序原生接入

这种接入方式使用的是小程序原生客服组件，需要您这边填写小程序appid以及小程序密钥（AppSecret），这两个参数均在小程序后台：左下角的设置-开发设置中进行获取。

小程序后台设置.png

为了避免我方频繁去通过appid和appsecret去请求微信接口导致access_token刷新超频而发送消息失败，需要您这边提供一个接口用于提供access_token获取url接口。 说明：该接口需要返回一个access_token的纯字符串。我们在每次发消息的时候都会去获取，您需要通过这个url来控制access_token的刷新频次，避免超频。

access_token获取url接口返回示例如图：

access_token获取.png

第一步：设置-在线客服-微信小程序-原生接入中点击立即绑定，填写小程序信息。

在小程序后台必须需要获取到：

小程序名称

小程序ID（APPID）

小程序秘钥(APISecret)/授权码（access_token）获取url接口

在填写好相应的信息后选择对应的流程，点击“下一步”

第二步：接入配置

接入配置.png

在客服系统点击确认后，将生成的“URL地址”“Token（令牌）”“EncodingAESKey”复制到小程序后台的“消息推送配置”中，将”接入配置”里的信息复制到”消息推送配置” 中

第三步：消息加密方式和数据格式

a、消息加密方式选择“安全模式”

b、数据格式必须为“XML”,点击“保存”

第四步：在小程序页面引入在线客服组件

小程序开发中在需要接入在线客服的小程序中引入小程序原生客服组件concat button；如小程序中原本就是使用的小程序客服组件则忽略本步骤。 session-from传值：JSON.stringify后的json信息。如：

    session-from="{{customField}}"

如需使用专属坐席：请在otherParams字段中添加vipAgent数据。

customField示例：

    customField:JSON.stringify({
        "userInfo":{
            "nickName":"117",
            "gender":1,
            "language":"zh_CN",
            "city":"Shijiazhuang",
            "province":"Hebei",
            "country":"China",
            "avatarUrl":"https://thirdwx.qlogo.cn/mmopen/vi_32/PiajxSqBRaEIouPJVr3gSHk0b0xZyDEia4Rlnb6PAXQm37scRIGbNTRDiaD6icicibb3P9Qks8xU826NqNuG1l5r7x9Q/132"
        },
        "otherParams":{
            "职业":"vtuber",
            "姓awda名":"yuudachi!",
            "年龄":24,
            "会员":true,
            "超长数据":"1234567890",
            "超长数据1":"abcdefghijklmnopqrstuvwxyz",
            "超长数据2":"ABCDEFGHIJKLMNOPQRSTUVWXYZ",
            "超长数据3":"`~!@#$%^&*()_+-=[]{};:\"",
            "超长数据4":"',./<>?",
            "user_labels":{
                "vip":"false",
                "city":"beijing"
            },
            "vipAgent": "606692848d81f6001e09b3d8"
        }
    })

字段解释 userInfo 微信返回的访客信息,也可自行写入

名称 类型 备注
nickName string 访客昵称
gender Number 访客性别
language string 访客微信语言
city string 访客城市
province string 访客省份
country string 访客国家
avatarUrl string 访客头像

otherParams json格式 自行对接的其他参数

注：由于微信那边限制的，session-from里面的字符串长度总数不能超过1024个字符

2.小程序sdk接入

若第5步搜索不到插件时，请直接跳到第7步即可，再看第8步。

  1. 打开微信公众平台，使用绑定小程序的微信号进行扫码登录或者账号密码登录；
  2. 进入后台以后，点击左侧的「设置」按钮，进入设置页面；
  3. 点击上方的「第三方设置」标签，进入标签页；
  4. 在下方的「插件管理」部分，点击右侧的「添加插件」按钮，打开弹窗；
  5. 输入「7moorSDK」然后回车，即可搜索出七陌的小程序插件，选中该插件后，点击弹窗下方的「添加」按钮；填写申请说明，继续点击弹窗下方的「添加」按钮；
  6. 提示「已发送申请」后，等待插件开发者确认后，该插件由「待确认」状态变为「已通过」状态，即可使用；
  7. 根据微信公众平台的小程序插件使用文档中的「引入插件代码包」部分介绍所示。打开「最新版」的微信开发者工具，在您的小程序项目的app.json或index.json中引入插件，即可接入七陌的访客端服务，代码如下：
{
  "pages": [...],
  "plugins": {
    "QIMOSDK": {
      "version": "0.0.10",
      "provider": "wxad7a35e324644a40"
    }
  }
}
  1. 保存代码后，如果在调试器的“Console”中有报错提示：插件未授权使用。请点击蓝色下划线的“
  2. 插件”按钮，会弹出“添加插件”弹窗，弹窗内即“7moorSDK”的介绍，点击右侧绿色的“添加”按钮即可。按钮与弹窗如下图所示：

添加插件.png

打开客服页面

七陌访客端向用户暴露了一个名为chat的页面进行展示，您可以在想打开七陌访客端的地方（在 xxx.wxml 或 xxx.js 中），添加跳转代码即可，代码如下：

<!--xxx.wxml-->
<navigator url="plugin://QIMOSDK/chat">
  联系客服
</navigator>

如果在js文件中使用，推荐使用wx.navigateTo的形式进行跳转，如果使用了wx.redirectTo进行重定向，那么进入客服页面后，再点击左上角的返回按钮会导致您的原有页面丢失或者返回报错。

// xxx.js
gotoPlugin() {
  wx.navigateTo({
    url: 'plugin://QIMOSDK/chat',
  });
},

用户功能对接配置

（一）初始化类型

该类型的接口需要在跳转chat页面之前调用，使用样例如下所示：

1. 访客端基础配置

需要您使用贵企业在我司的 V7联络云 中申请的渠道id，即 accessId 进行初始化配置，代码如下：

var QIMOSDK = requirePlugin('QIMOSDK');

var accessId = '七陌生成的唯一渠道Id，形如 Jm6Pb0KpgafpcMcb 的16位随机字符串';
QIMOSDK._initAccessId(accessId);

2. 访客自定义信息

此处只接受这3个字段，均与访客的信息相关，如果不传那么后台会默认生成一套访客信息模板

QIMOSDK._initUserParams({
  uid: '访客的唯一标识', // 可以配合后端获取微信的openid
  nickName: '访客的昵称', // 可以使用 wx.getUserProfile() 获取
  avatar: 'https://img2.baidu.com/it/u=2421505363,3507499484&fm=26&fmt=auto&gp=0.jpg', // 访客的头像
});

3. 访客其他自定义参数

此处不做特殊要求，至于具体需要传什么，请与对接人员最终敲定

QIMOSDK._initOtherParams({
  // 比如，某用户A，想要传一个性别字段
  gender: 'male', // 字符串 | 数值 | 布尔值 | 对象 | 函数 | null | ...
});

4. 输入框右侧 ➕ 的展示类型

可配置“加号”图标何时展示，点击加号可展开更多功能，比如拍照、图片、自定义按钮等。

可选参数如下： - always: 一直展示，默认值 - onlyRobot: 仅机器人节点展示 - onlyAgent: 仅人工节点展示

配置代码如下：

QIMOSDK._initMoreBtnsShowType('onlyAgent');

（二）监听回调函数类型

该类型的接口的调用与会话接入顺序无关，可在跳转至客服页面后再调用

1. 自定义事件（加号按钮内配置的自定义按钮）

该事件的触发，是在V7联络云座席端的样式配置中，配置自定义按钮时填写的事件名称。使用方式如下所示：

QIMOSDK._onCustomEventCallBack((params, navigateBack) => {
  // 打开 订单列表 的事件
  if (params._eventType === '_onOpenOrderCard') {
    // 如果想跳转到用户自身小程序的页面，需要先调用第三个参数的 navigateBack() 方法，再进行后面的跳转逻辑；
    // 并且，调用完后，如果跳转报错：navigateTo:fail rejected due to no permission currently
    // 需要将后续的逻辑放到任务队列中，比如：setTimeout(() => { todo sth ... }, 500);
    navigateBack();
    setTimeout(() => {
      this.openCardListPage();
    }, 500);
  }
});

2. 链接被点击

可以接收消息中超链接被点击后的回调函数，并接收一个参数（链接相关的信息）。使用方式如下所示：

QIMOSDK._onTapHrefCallBack((params, navigateBack) => {
  console.log('======= params:', params);
  // 包括但不限于以下属性
  // href: "https://www.baidu.com"
  // target: "_blank"
  // innerText: "超链接的名称"
  // ...
  navigateBack(); // 该方法的使用情况同上
});

3. 点击附件时

当用户点击附件进行下载时，默认是走插件内部默认的下载逻辑，但如果在配置时传了该回调函数，就会拦截附件的信息进行抛出，并且不走默认的下载逻辑了。使用方式如下所示：

QIMOSDK._onDownloadFile((file) => {
  console.log('======= file:', file);
  // name: 文件名
  // url: 文件链接
});

（三）直接调用函数类型

该类型的函数为直接调用的形式，何时使用何时调用即可。

1. 发送文本消息

接入会话后，调用此接口能且仅能发送纯文本类型的消息。使用方式如下所示：

wx.redirectTo({
  url: 'plugin://QIMOSDK/chat',
  success: function(res) {
    const msg = '订单编号：20210719113430';
    QIMOSDK._sendTextMessage(msg);
  },
  fail: function(res) {
    console.log('======= fail res:\n', res);
  },
});

注：此处为何使用 wx.redirectTo() ？

因为跳转到客服页面后，会涉及到再次返回上一页的需求，如果使用的 wx.navigateTo() 进行跳转，那么下一次会返回到当前页。而我当前页只是一个发送消息前的查看页面，所以直接用 wx.redirectTo() 替换掉当前页。（后面的 wx.redirectTo() 用法同理）

2. 发送订单卡片（或商品卡片）

接入会话后，调用此接口能且仅能发送订单卡片类型的消息。使用方式如下所示：

wx.redirectTo({
  url: 'plugin://QIMOSDK/chat',
  success: function(res) {
    const msg = {
      orderNum: '0123456789012345', // 单号
      orderNumName: '单号:', // 单号的标题
      orderList: [ // 列表
        {
          imgUrl: 'https://dpic.tiankong.com/1n/e2/QJ6231550446.jpg@!350h', // 图片
          content: '这是商品描述或者为订单描述文字说明说明说明', // 备注
          price: '￥9999' // 价格
        },
        {
          imgUrl: 'https://dpic.tiankong.com/1n/e2/QJ6231550446.jpg@!350h', // 图片
          content: '这是商品描述或者为订单描述文字说明说明说明', // 备注
          price: '￥9999' // 价格
        },
      ],
    }
    QIMOSDK._sendOrderCardMessage(msg);
  },
  fail: function(res) {
    console.log('======= fail res:\n', res);
  },
});

更多配置...