七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

功能配置

自定义配置

_$setCustomConfig

接口描述

配置一些其他的自定义内容

参数说明

_$setCustomConfig(config: CustomConfig): Promise<void>

CustomConfig

名称类型必填默认值说明
fromTitlestring否-自定义访客咨询来源页的标题,无法自动获取,和 referrer 一起使用
referrerstring否-自定义访客咨询来源页的url,无法自动获取,和 fromTitle 一起使用
customerAvatarstring否-自定义客服头像的url, (注意:设置了此项,管理端的所有客服头像设置将会对此小程序 SDK 无效)
APPbackPopnumber否0聊天页面点击返回的时候是否弹出 关闭挽留弹窗0:不弹起1:只弹起关闭挽留弹窗2: 弹起关闭挽留弹窗和满意度评价弹窗(全屏模式不支持)
bidnumber否-1、普通企业不需要传bid
2、主企业下绑定的小程序,进行咨询主企业,bid只能传主企业的code不能为空
3、主企业下绑定的小程序,进行咨询子企业,bid只能传入子企业的shopId
4、子企业下绑定的小程序,bid只能传-1或不传(不能传入商铺id,否则连不上客服),子企业下绑定的小程序不能转接到主企业
注:如果用新包,正常传递bid,接入之后,该访客之前与老版本咨询的消息将无法看到
transferToHumannumber否1指定机器人 id 时是否支持转人工。0:不支持,1:支持(版本要求 >= 1.19.1)
templateIdnumber否-指定访客端样式模板 id,id 获取途径见【注1】(版本要求 >= 1.18.3)
robotIdnumber否-指定机器人 id ,id 获取途径见【注2】(版本要求 >= 1.18.3)
shortcutTemplateIdnumber否-机器人常见快捷入口模版id,id 获取途径见【注3】
qtypenumber否-机器人常见问题模板id,id 获取途径见【注4】(版本要求 >= 1.19.2)

【注1】访客端样式模版 templateId 获取路径:管理端首页 - 在线客服 - 设置 - 访客端 - 样式设置

【注2】机器人 robotId 获取路径:管理端首页- 在线客服 - 在线接入 - 网站 - 机器人开关

【注3】常见快捷入口 shortcutTemplateId 获取路径:管理端首页 - 在线机器人 - 设置 - 导航菜单 - 常见快捷入口

【注4】常见问题模版 qtype 获取路径:管理端首页 - 在线机器人 - 设置 - 导航菜单 - 常见问题 - 常见问题模版

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$setCustomConfig({
	referrer: '/page/home/index',
	customerAvatar: 'https://ysf.qiyukf.net/operation/8de1f12e2420c26c00e7abe194b28f58',
	templateId: 39298043
});

商品卡片

配置商品卡片

_$configProduct

接口描述

在打开咨询窗口时,还可以带上用户当前正在浏览的商品或订单信息。

参数说明

_$configProduct(product: Product):void;

Product

名称类型必填默认值说明
cardTypenumber否-卡片类型,共三种类型。0:商品,1:订单,2:自定义,推荐填写
titlestring否-商品标题,长度限制为 100 字符,超过自动截断
descstring否-商品详细描述信息,长度限制为 300 字符,超过自动截断
goodsCIdstring否-商品类目ID,长度限制为 100 字符,填写后有助于机器人识别商品和后续业务
goodsCNamestring否-商品类目名称,长度限制为 10 字符,如生鲜食品
goodsIdstring否-商品ID,长度限制为 100 字符,商品唯一标识符,填写后有助于机器人识别商品和后续业务,当卡片类型为商品时,推荐填写
notestring否-商品备注信息(价格,套餐等),长度限制为 100 字符,超过自动截断
picturestring否-缩略图图片的 url,该 url 需要没有跨域访问限制,否则在客服端会无法显示
pictureMode'scaleToFill' | 'aspectFit' | 'aspectFill'否'scaleToFill''scaleToFill':保持现状,拉伸为正方形'aspectFit':图片按原比例展示,高的图片两边有白色背景,宽的图片上下有白色背景,展示成正方形'aspectFill':图片按原比例展示,裁剪掉一部分,展示成正方形
urlstring否-商品信息详情页 url,长度限制为 1000 字符,超长不会自动截断,但会发送失败
isShownumber否0是否在访客端显示商品消息,0:不显示,1:显示,默认为 0,即客服能看到此消息,但访客看不到,也不知道该消息已发送给客服
tagsTag[]否-展示在客服端的一些可操作入口,默认为空,每个 tag 在客服端将展示为一个按钮
sendByUsernumber否0是否需要用户手动发送,0:自动发送,1:手动发送,默认为 0当为 1 的时候,商品的下面将出现一个按钮,用户可以点击该按钮发送商品
actionTextstring否-手动发送按钮的文本,默认文本为 "发送链接"
actionTextColorstring否-手动发送按钮文本的颜色,十六进制颜色例如:0xFFDB7093
extraParamany否-额外参数,商品卡片点击回调时能接收到的除url外的额外参数
sendProToRobotnumber否0机器人会话阶段是否发送商品卡片,0:不发送商品卡片,1:发送商品卡片,默认为 0
sendKefuOfflinenumber否0人工客服不在线进留言的时候是否发送,1:是,0:否,默认为 0
intentstring否-意图名称
orderIdstring否-订单 id,长度限制为 100 字符,订单的唯一标识符;cardType = 1 时生效
infostring否-​卡片附加信息,信息不展示在前端卡片中,长度限制为100字符,超过自动截断
agentIdnumber否-​支持指定Agent接待,不需要调起Agent则参数值上报为空即可。若同时命中intent的小模型意图时,会优先返回小模型答案

Tag

名称类型必填说明
labelstring是标签名称
urlstring否非必填,如果没有 focusIframe 字段,或者没有匹配到 iframe,就以新窗口打开这个链接
focusIframestring否定位到工作台右侧面板 iframe 的标识,以 iframe 的名称匹配
dataany否以 postMessage 形式发送的数据,数据格式不限

代码示例

const myPluginInterface = requirePlugin('myPlugin');
const product = {
  title: '任天堂(Nintendo)Switch游戏机',
  desc: '任天堂(Nintendo) Switch NS NX掌上游戏机便携 塞尔达马里奥新款游戏机 主机不锁 日版黑机彩色手柄+中文赛/塞尔达传说(指南+地图)',
  note: '$2330',
  picture: 'https://img10.360buyimg.com/n5/s75x75_jfs/t4030/290/29851193/293745/d5e2b731/58ac3506Nbb57b5f6.jpg',
  url: 'https://www.qi.163.com/',
  isShow: 1,
  sendByUser: 1,
  extraParam: {
    param1: '_$onClickAction事件回调中可能需要的额外参数'
  }
};
myPluginInterface._$configProduct(product);

主动发送商品卡片

_$sendProduct

接口描述

在打开咨询窗口后,可以调用此 API 实时发送商品卡片

参数说明

_$sendProduct(product: Product):void;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$sendProduct(product);

清空商品卡片

_$clearProduct

接口描述

清空配置的商品卡片,若企业有多个咨询入口,且存在部分入口配置了商品卡片,部分入口未配置商品卡片,可调用该方法保证商品卡片不会在未配置的咨询入口意外发送

参数说明

_$clearProduct(product: Product):void;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$clearProduct();

自定义卡片

版本 2.2.0 开始支持

配置自定义卡片

_$configCustomCard

版本 2.2.0 开始支持

接口描述

在打开咨询窗口时,还可以带上用户当前正在浏览的商品或订单等信息。

参数说明

_$configCustomCard(cardInfo: CardInfo):void;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
const cardInfo = {
  sendByUser: 1, // 默认0,1手动发送,0自动发送(非1为否)
  hideAction: 0, // sendByUser=1的时候会展示发送卡片按钮,可以通过 hideAction:1 强制隐藏按钮,默认 0
  actionText: '发送', // 发送按钮文案
  actionTextColor: '#0000FF', // 发送按钮文案颜色(16进制格式)
  // 气泡内的消息
  cards: [
    {
      type: 'image',
      img: 'https://res.qiyukf.net/operation/e32bbc516ee7c88031aeefd8261b3f8c', // 图片url
      url: 'https://qiyukf.com/', //  跳转 url
      style: {
        pt: 16, // 上边距
        pb: 16, // 下边距
        pl: 24, // 左边距
        pr: 24, // 右边距
        divider: 1, // 分割线
      },
    },
  ], 
  // 气泡外的消息
  floatCards: [
    {
      type: 'product',
      data: [
        {
          id: 'floatCards_20240528001_1', // 商品id
          picture: 'https://res.qiyukf.net/operation/e32bbc516ee7c88031aeefd8261b3f8c', // 商品图片
          title: '111标题title_floatCards_20240528001_1',
          desc: '111描述desc_floatCards_20240528001_1', // 描述
          price: '¥111.11', // 价格
          url: 'https://qiyukf.com/', // 跳转链接
          action: 0, // 0 点击跳转, 1 点击发送对应的商品卡片 (只试用于访客端)
        },
      ],
      style: {
        pt: 16, // 上边距
        pb: 16, // 下边距
        pl: 24, // 左边距
        pr: 24, // 右边距
        divider: 0, // 分割线,默认1
      },
    },
  ],
};

myPluginInterface._$configCustomCard(cardInfo);

主动发送自定义卡片

_$sendCardMessage

版本 2.2.0 开始支持

接口描述

在打开咨询窗口后,可以调用此 API 实时发送自定义卡片

参数说明

_$sendCardMessage(cardInfo: CardInfo):void;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$sendCardMessage(cardInfo);

清空自定义卡片

_$clearCustomCard

版本 2.2.0 开始支持

接口描述

清空配置的商品卡片,若企业有多个咨询入口,且存在部分入口配置了卡片,部分入口未配置卡片,可调用该方法保证卡片不会在未配置的咨询入口意外发送

在打开咨询窗口后,可以调用此 API 实时发送自定义卡片

参数说明

_$clearCustomCard():void;

代码示例

myPluginInterface._$clearCustomCard();

自定义分配客服

_$configStaffId

接口描述

若企业有多个咨询入口,为提高咨询效率,可在不同咨询入口设置对应的人工客服接待。

参数说明

_$configStaffId(staffId: number):void;
名称类型必填说明
staffIdnumber是指定ID后,进入聊天页面时,会直接以此ID去请求对应的人工客服

人工客服ID查询路径:管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-ID查询-客服及客服组ID查询

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$configStaffId(30010);

自定义分配客服组

_$configGroupId

接口描述

若企业有多个咨询入口,为提高咨询效率,可在不同咨询入口设置对应的人工客服组接待。

参数说明

_$configGroupId(groupId: number):void;
名称类型必填说明
groupIdnumber是指定ID后,进入聊天页面时,会直接以此ID去请求对应的客服组,服务组会随机分配客服组中可用客服接待。

人工客服ID查询路径:管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-ID查询-客服及客服组ID查询

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$configGroupId(30330);

指定分流客服组后开启机器人

_$setRobotShuntSwitch

接口描述

如果已经指定分流客服或者客服组时,如果需要开启机器人,需要手动配置机器人开关。

参数说明

_$setRobotShuntSwitch(isOpen: number):void;
名称类型必填说明
isOpennumber是指定分流客服组后开启机器人,0:不开启,1:开启,默认 0

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$setRobotShuntSwitch(1);

指定分流模版

_$configShuntId

接口描述

指定访客选择多入口分流模版

参数说明

_$configShuntId(shuntId: number):void;
名称类型必填说明
shuntIdnumber是分流模版 id

人工客服ID查询路径:管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-多入口分配自定义模板

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$configShuntId(30340);

设置聊天窗口的标题

_$configTitle

接口描述

七鱼插件提供自定义聊天窗口 chat 页面的标题(即微信小程序的navigationBarTitleText值)的功能。(默认值为在线客服)

参数说明

_$configTitle(title: string):void;
名称类型必填说明
titlestring是页面标题

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$configTitle('七鱼客服');

监听链接点击事件

_$onClickAction

接口描述

如果用户或者客服发送的文本消息中带有 URL 链接,SDK 将会复制该链接。用户点击这个链接后,允许应用自己处理这个点击事件,用于在应用中做自定义响应操作。

参数说明

_$onClickAction(cb: function):void;

回调函数中参数格式:

名称类型说明
dataData链接信息
navigateTowx.navigateTonavigateTo 方法,由于微信限制,插件页作用域只能通过此方法跳转
switchTabwx.switchTabswitchTab 方法,由于微信限制,插件页作用域只能通过此方法跳转(插件版本要求 >= 2.2.0)
navigateToMiniProgramwx.navigateToMiniProgramnavigateToMiniProgram 方法,由于微信限制,插件页作用域只能通过此方法跳转(插件版本要求 >= 2.2.7)

因小程序插件回调中,主程序无法直接调用自身的navigateTo等函数进行跳转,所以额外提供参数供使用方进行页面跳转

Data

名称类型说明
urlstring访问的链接地址
fromstring链接访问的来源模块
extraParamany额外参数信息,配置商品卡片 _$configProduct 时可传入

代码示例

myPluginInterface._$onClickAction((data, navigateTo, switchTab, navigateToMiniProgram) => {
  console.log('事件参数', data)
  // 注意此处必须使用 navigateTo 或 switchTab 或 navigateToMiniProgram
  // 跳转到当前小程序其他页面
  navigateTo({
    url: `/pages/test/index?id=${data?.extraParam?.id}`
  });
  
  // 跳转到其他小程序
  navigateToMiniProgram({
    appId: 'wx7...68b',
    path: `/pages/index/index?id=${data?.extraParam?.id}`,
    envVersion: 'release',
    success(res) {
      console.log('打开其他小程序成功', res);
    },
    fail(err) {
      console.error('打开其他小程序失败', err);
    },
  })
})

配置链接复制行为

_$configAutoCopy

接口描述

配置在自定义点击事件的同时,是否进行链接文本的复制操作。

参数说明

_$configAutoCopy(autoCopy: number):void;
名称类型说明
autoCopynumber0:关闭默认链接复制操作1:开启默认链接复制操作

代码示例

myPluginInterface._$configAutoCopy(0);

监听自定义事件点击

_$onEntranceClick

接口描述

人工会话下,快捷入口、操作面板中自定义事件点击回调

参数说明

_$onEntranceClick(cb: function):void;

回调函数中参数格式:

名称类型说明
dataData数据信息
navigateTowx.navigateTonavigateTo 方法,由于微信限制,插件页作用域只能通过此方法跳转
switchTabwx.switchTabswitchTab 方法,由于微信限制,插件页作用域只能通过此方法跳转(插件版本要求 >= 2.2.0)
navigateToMiniProgramwx.navigateToMiniProgramnavigateToMiniProgram 方法,由于微信限制,插件页作用域只能通过此方法跳转(插件版本要求 >= 2.2.8)

因小程序插件回调中,主程序无法直接调用自身的navigateTo函数进行跳转,所以额外提供参数供使用方进行页面跳转

Data

名称类型说明
actionstring事件类型
labelstring入口名称
dataany自定义数据

代码示例

myPluginInterface._$onEntranceClick((data, navigateTo, switchTab) => {
  console.log('事件参数', data)
  // 注意此处必须使用 navigateTo 或 switchTab
  navigateTo({
    url: `/pages/test/index?id=${data.extraParam.id}`
  })
})

用户注销

_$logout

接口描述

如果一个非匿名用户需要清除用户信息,需要手动调用 _$logout 方法

参数说明

_$logout():Promise<void>;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
const doLogout = async () => {
  await myPluginInterface._$logout()
}

获取未读消息数量

_$getAllUnreadCount

接口描述

获取当前未读消息数量。打开七鱼聊天窗口后可用,如果要在不打开七鱼聊天窗口的情况下获取当前未读消息数量,可以对接后端接口:未读消息查询接口

参数说明

_$getAllUnreadCount():number;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
const total = myPluginInterface._$getAllUnreadCount();
console.log('当前未读消息总数: ', total)

监听未读消息

_$onunread

接口描述

监听未读消息,打开七鱼聊天窗口后可用

参数说明

_$onunread(cb:function):void;

回调函数中参数格式:

名称类型说明
totalnumber未读消息数量
messageQyMessage新增的未读消息

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$onunread(res => {
  const { total, message } = res;
  console.log('当前未读消息总数: ', total)
  console.log('新增未读消息: ', message)
});

清空所有未读消息

_$clearUnreadCount

接口描述

清空所有未读消息,打开七鱼聊天窗口后可用

参数说明

_$clearUnreadCount():number;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$clearUnreadCount(); // 会触发_$onunread 回调
console.log('未读消息清空完成!');

历史消息处理

_$setHistoryLimit

2.2.0 版本后已废弃

接口描述

设置历史消息保留条数,默认100条,鉴于小程序性能问题,不建议设置过长历史消息条数

参数说明

_$setHistoryLimit(val: number):void;

代码示例

const myPluginInterface = requirePlugin('myPlugin');
myPluginInterface._$setHistoryLimit(200); // 保留200条历史消息

监听文件点击

_$onFileOpenAction

2.2.0 版本后已废弃,插件内部已处理(对于 wx.openDocument 支持的文件可直接预览,其他文件格式可以复制文件链接)

接口描述

处理用户打开文件操作,默认情况下sdk自行处理包括图片、音频、视频类型的文件打开操作,但是由于小程序对于插件api调用的限制,sdk无法直接打开文档及其他类型的问题,此时需要用户自行监听事件进行处理

参数说明

_$onFileOpenAction(cb: function):void;

回调函数中参数格式:

名称类型说明
namestring文件名称
urlstring文件下载地址
tempFilePathstring文件本地临时地址
sizenumber文件大小
md5string文件md5

代码示例

调用该函数后,对于sdk无法处理的文件打开操作会通过回调事件,由用户自行处理

// 简单示例
myPluginInterface._$onFileOpenAction((fileObj) => {
  const name = fileObj.name || '';
  const nameArr = name.split('.');
  const ext = (nameArr[nameArr.length - 1] || '').toLocaleLowerCase();
  // 针对文档类型,直接调用微信api进行打开
  if (['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'pdf'].includes(ext)) {
    wx.openDocument({
      filePath: fileObj.tempFilePath,
      fileType: ext,
      success: function (res) {}
    })
  } else {
    wx.showToast({
      title: '暂不支持该文件类型预览'
    })
  }
})

全面屏适配

_$configFullScreen

接口描述

由于微信小程序本身的限制,导致用户全局配置navigationStyle: 'custom'时,会导致插件页面的导航栏被隐藏从而无法进行页面后退,并且由于微信小程序并没有相关api提供到插件开发者去控制导航栏,目前考虑到部分用户业务场景无法通过配置单独的页面进行导航栏显示/隐藏控制,故七鱼插件为开发者提供了全面屏配置参数(不支持返回弹评价功能)

代码示例

myPluginInterface._$configFullScreen(true);

禁止发送语音功能

_$setVoiceBtnSwitch

接口描述

提供配置开关可以禁止发送语音的功能,界面表现上为发送语音按钮不可见。

代码示例

myPluginInterface._$setVoiceBtnSwitch(false);

设置宿主环境

_$setHostApp

版本 1.19.3 开始支持

因微信小程序限制,部分 api 在插件中无法调用,可以通过此 api 设置宿主环境解决调用限制

代码示例

myPluginInterface._$setHostApp(wx);

设置机器人超长消息是否折叠展示

_$setRobotMessageFold

版本 2.5.0 开始支持

通过配置项控制机器人超长消息是否折叠 ,默认为折叠状态

代码示例

myPluginInterface._$setRobotMessageFold(isFold: 0|1 );
名称类型必填说明
isFold0 | 1是可以根据配置值0或者1来控制机器人超长消息是否折叠,0为不折叠,1为折叠,默认为1

这篇文档有帮助吗?

目录