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

功能配置API

自定义配置

setCustomConfig

接口描述

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

参数说明

setCustomConfig(config: CustomConfig): void

CustomConfig

名称类型说明
fromTitlestring自定义访客咨询来源页的标题,无法自动获取,和 referrer 一起使用
referrerstring自定义访客咨询来源页的url,无法自动获取,和 fromTitle 一起使用
customerAvatarstring自定义客服头像的url
APPbackPopnumber聊天页面点击返回的时候是否弹出 关闭挽留弹窗0:不弹起1:只弹起关闭挽留弹窗2: 弹起关闭挽留弹窗和满意度评价弹窗(全屏模式不支持)
transferToHumannumber指定机器人 id 时是否支持转人工,默认1
templateIdnumber指定访客端样式模板 id,id 获取途径见【注1
robotIdnumber指定机器人 id ,id 获取途径见【注2
shortcutTemplateIdnumber机器人常见快捷入口模版id,id 获取途径见【注3】
qtypenumber机器人常见问题模板id,id 获取途径见【注4

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

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

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

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

代码示例

setCustomConfig({
	referrer: '/page/home/index',
	customerAvatar: 'https://ysf.qiyukf.net/operation/8de1f12e2420c26c00e7abe194b28f58',
	templateId: 39298043
});

商品卡片

设置商品卡片

configProduct(product: Product)

功能描述

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

商品示例图

订单示例图

参数说明

名称类型必须描述
通用参数cardTypestring否卡片类型,共三种类型。商品: 0,订单: 1,自定义: 2,推荐填写
sendByUsernumber否是否由访客手动发送,1为是,其他参数为否
shownumber否访客是否可见,1可见,其他参数访客不可见(但客服都是可见的)sendByUser=1 时,show强制为1
actionTextstring否发送按钮文案,需设置 sendByUser 生效
actionTextColorstring否发送按钮文案颜色,需设置 sendByUser 生效
sendProToRobotnumber否此字段为机器人会话是否发送商品卡片,为1展示机器人阶段发送商品卡片,为0则机器人阶段不发送商品卡片而是人工会话中发送
intentstring否意图名称
sendKefuOfflinenumber否人工客服不在线进留言的时候是否发送 1为是,0为否,默认为否
paramsobject否流程参数
infostring否​卡片附加信息,信息不展示在前端卡片中,长度限制为100字符,超过自动截断
agentIdnumber否​支持指定Agent接待,不需要调起Agent则参数值上报为空即可。若同时命中intent的小模型意图时,会优先返回小模型答案
商品picturestring是商品的缩略图地址
titlestring是商品的展示标题
descstring否商品展示的简要描述
notestring否商品备注,展示位置同商品价格,优先级高于商品价格
pricestring否商品的价格(已废弃,请使用 note 替代)
goodsCIdstring否商品类目ID,长度限制为 100 字符,填写后有助于机器人识别商品和后续业务
goodsCNamestring否商品类目名称,长度限制为 10 字,如生鲜食品
goodsIdstring否商品ID, 长度限制为 100 字符,商品唯一标识符,填写后有助于机器人识别商品和后续业务,当卡片类型为商品时,推荐填写
tagsTag[]否订单类消息展示的功能按钮,tag每一项为{"label": "打开七鱼网址","url": "[https://qi.163.com](https://qi.163.com)"},label为按钮的名称,url为打开的链接
urlstring否点击商品跳转到的链接地址
订单picturestring是商品的缩略图地址
titlestring是商品的展示标题
descstring否商品展示的简要描述
goodsIdstring否商品ID, 长度限制为 100 字符,商品唯一标识符,填写后有助于机器人识别商品和后续业务,当卡片类型为商品时,推荐填写
goodsCIdstring否商品类目ID,长度限制为 100 字符,填写后有助于机器人识别商品和后续业务
payMoneystring否商品支付的价格
orderIdstring是订单的id
orderTimestring否下单时间
orderSkustring否订单的sku描述信息
orderCountstring否订单中商品数量
orderStatusstring否订单交易状态
orderStageTypenumber否订单状态分类 售前阶段:10000 发货前阶段:20000 发货后阶段:30000 售后阶段:40000
tagsTag[]否订单类消息展示的功能按钮,tag每一项为{"label": "打开七鱼网址","url": "[https://qi.163.com](https://qi.163.com)"},label为按钮的名称,url为打开的链接
urlstring否点击商品跳转到的链接地址
自定义模版templatestring是模板类型(当前支持"pictureLink"即图片链接模板)
picturestring是图片地址
urlstring否点击图片跳转到的链接地址

示例代码

import { configProduct } from '@ysf/sdk';
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事件回调中可能需要的额外参数',
  },
};

configProduct(product);

清除商品卡片

clearProduct()

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

主动发送商品卡片

sendProductMessage(product: ProductVO)

发送商品卡片,用于用户切回自己app页面,选择商品卡片发送。注意必须在打开过页面后才能使用。

/ 商品卡片标签
export type CardTagVO = {
  label: string;
  url: string;
  focusIframe: string;
  data: any;
};

// 商品卡片配置类型美剧
export enum ProductCardTypeEnum {
  PRODUCT = 0, // 商品卡片
  ORDER = 1, // 订单卡片
  CUSTOM = 2, // 自定义卡片
}

// 订单阶枚举
export enum OrderStageTypeEnum {
  PRE_SALE = 10000, // 售前阶段
  BEFORE_SHIPMENT = 20000, // 发货前阶段
  AFTER_SHIPMENT = 30000, // 发货后阶段
  AFTER_SALE = 40000, // 售后阶段
}

// 商品卡片配置
export type ProductVO = {
  cardType?: ProductCardTypeEnum;
  sendByUser?: number;
  auto?: number;
  show?: number;
  actionText?: string;
  actionTextColor?: string;
  sendProToRobot?: number;
  picture: string;
  title: string;
  desc: string;
  url: string;
  note: string;
  price?: string;
  goodsId?: string;
  goodsCId?: string;
  goodsCName?: string;
  intent?: string;
  payMoney?: string;
  orderId?: string;
  orderTime?: string;
  orderSku?: string;
  orderCount?: string;
  orderStatus?: string;
  orderStageType?: OrderStageTypeEnum;
  isShow?: number;
  tags?: CardTagVO[];
  extraParam?: Record<string, string>;
  floatCardSend?: number;
};

自定义卡片

设置自定义卡片

configCustomCard(product: cardMessageVO)

在打开咨询窗口时,发送自定义卡片。

清除自定义卡片

clearCustomCard()

清除自定义卡片,即打开咨询的时候不在发送自定义卡片【先前设置过】

实时发送自定义卡片

sendCardMessage(product: cardMessageVO)

用于连接到七鱼客服后,在会话中,发送自定义卡片。

export type cardMessageVO = {
  cards?: Icard[],
  floatCards?: IFloatCard[],
  sendProToRobot? 1| 0:  //1:开 默认0 
}
type ICard =
  | TitleOptions
  | RichOptions
  | SubTitleOptions
  | ImageOptions
  | ProductOptions
  | OrderOptions
  | FlowOptions
  | ButtonOptions
  | LinkOptions
  | TagOptions;

type IFloatCard = ProductOptions | ButtonOptions | TagOptions;

enum MoudleType {
  TITLE = 'title',
  RICH = 'rich',
  SUBTITLE = 'subtitle',
  IMAGE = 'image',
  PRODUCT = 'product',
  ORDER = 'order',
  FLOW = 'flow',
  BUTTON = 'button',
  LINK = 'link',
  TAG = 'tag',
}

interface TitleOptions {
  type: MoudleType.TITLE;
  content: string; //内容
  url?: string; // 超链接
  img?: string; // 图片加文本的图片url
  style?: {
    fontSize?: string | number; // 文字大小,默认14px
    fontColor?: string; // 字体颜色
    divider?: 0 | 1; // 是否添加分割线默认有分割线,最后一个元素没有
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 富文本模版的配置
 */
interface RichOptions {
  type: MoudleType.RICH; // 富文本
  content: string; // 内容
  style?: {
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
    divider?: 0 | 1; // 分割线
  };
}

/**
 * 副标题模版的配置
 */
interface SubTitleOptions {
  type: MoudleType.SUBTITLE;
  img?: string; // 图片url
  content: string;
  subContent?: string; // 显示在右侧的
  url?: string; // 跳转 url
  style?: {
    backgroundColor?: string; // 背景色
    divider?: 0 | 1; // 分割线
    fontSize?: number;
    fontColor?: string;
    subFontSize?: number;
    subFontColor?: string;
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 图片模版的配置
 */
interface ImageOptions {
  type: MoudleType.IMAGE; // 图片
  img: string; // 图片url
  url?: string; // 跳转 url
  style?: {
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 商品模版的配置
 */
export interface ProductOptions {
  type: MoudleType.PRODUCT; // 商品
  data: {
    id: string | number; // 商品id
    picture: string; // 商品图片
    desc: string; // 描述
    title: string; 标题
    price: string; // 价格
    url?: string; // actions 0的情况 跳转链接
    action?: 0 | 1; // 0 点击跳转【默认】, 1 点击发送对应的商品卡片 (只试用于访客端)
  }[];
  style?: {
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 订单模版的配置
 */
export interface OrderOptions {
  type: MoudleType.ORDER; // 订单
  orderId: string | number; // 订单id
  orderTime: string; // 下单时间
  data: {
    picture: string; // 商品图片
    desc: string; // 描述
    title: string; // 商品标题
    payMoney?: string; // 价格
    url?: string; // 跳转链接
    count?: string; // 订单商品数量 x 100
    sku?: string; // 商品sku描述
    status: string; // 交易状态
    action?: 0 | 1; // 0 点击跳转, 1 点击发送对应的订单卡片 (只试用于访客端)
  }[];
  style?: {
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 节点流程的配置
 */
export interface FlowOptions {
  type: MoudleType.FLOW; // 流程
  data: {
    id: string | number; // 流程id
    title: string; // 标题
    subtitle?: string; // 副标题
    current?: 1 | 0; // 当前步骤
  }[];
  style?: {
    fontSize?: number; // 主标题大小
    fontColor?: string; // 主标题颜色 有默认
    subFontSize?: number; // 副标题大小
    sunFontColor?: string; // 副标题颜色 有默认值
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 按钮模版的配置 TODO
 */
export interface ButtonOptions {
  type: MoudleType.BUTTON; // 按钮
  numInRow?: number; // 一行显示几个按钮 默认1个【浮动组件不生效】
  data: {
    title: string; // 标题
    action?: 0 | 1; // 0 点击跳转链接, 1 点击发送配置的文字(仅限访客)
    url?: string; // 跳转链接
    content?: string; // 发送的文字 action === 1 需要配置此内容
  }[];
  style?: {
    backgroundColor?: string; // 背景色
    fontColor?: string; // 文字颜色
    fontSize?: number; // 文字大小
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 卡片消息的配置
 */
export interface LinkOptions {
  type: MoudleType.LINK; // 链接
  content: string; // 标题
  url: string; // 跳转链接
  style?: {
    fontSize?: number; // 文字大小
    fontColor?: string; // 文字颜色
    divider?: 0 | 1; // 分割线
    pt?: number; // 上边距
    pb?: number; // 下边距
    pl?: number; // 左边距
    pr?: number; // 右边距
  };
}

/**
 * 标签
 */
export interface TagOptions {
  type: MoudleType.TAG; // 标签
  data: {
  	label: string; // 标签名称
    url?: string; // 非必填,如果没有 focusIframe 字段,或者没有匹配到 iframe,就以新窗口打开这个链接
    focusIframe?: string; // 定位到客服工作台右侧 iframe 的标识,以 iframe 的名称匹配
    data: any; // 以 postMessage 形式发送的数据,数据格式不限
  }[];
}

卡片消息【cards】支持所有的 10 种类型卡片,分别是:标题类型、富文本类型、副标题类型、图片类型、节点流程类型、商品类型、订单类型、按钮类型、跳转链接类型、标签类型。一条卡片消息可以包含多种类型的模板组合。

浮动卡片消息【floatCards】只支持商品类型、按钮类型和标签类型。

【建议内容长度在4000个字符以内,超过可能会有非预期表现】

具体效果可以参考卡片消息字段说明

分配指定客服

configStaffId(staffid: number)

功能描述

指定进线客服 staffid

示例代码

configStaffId(10001);

指定 staffid 后,进入聊天页面时,会直接以此 staffid 去请求对应的人工客服。

人工客服 ID 查询:管理端-应用-在线系统-设置-会话流程-会话分配-ID 查询-客服及客服组 ID 查询

分配指定客服组

configGroupId(groupid: number)

功能描述

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

示例代码

import { configGroupId } from '@ysf/sdk';
configGroupId(12);

指定 groupid 后,进入聊天页面时,会直接以此 groupid 去请求对应的客服组,服务组会随机分配客服组中可用客服接待。

客服组 ID 查询:管理端-应用-在线系统-设置-会话流程-会话分配-ID 查询-客服及客服组 ID 查询

监听点击链接

onClickUrl(cb: function)

功能描述

配置改回调后,用户点击这个链接后,允许应用自己处理这个点击事件,用于在应用中做自定义响应操作。

参数

名称类型描述
dataobjecturl: 访问的链接地址, from: 链接访问的来源模块, extraParam: cb 中可调用的变量参数

监听自定义事件

onCustomEvent(cb: function)

功能描述

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

参数

名称类型描述
dataobjectaction: 事件类型[custom]; label: 快捷入口名称; data: 快捷入口自定义数据

自动拷贝链接

configAutoCopy(autoCop: 1| 0)

功能描述

可以在点击链接的时候,复制链接操作,默认开。

注销用户

logout()

功能描述

用户注销,如果一个有名用户需要清除用户信息,需要手动调用 logout 方法。

获取消息未读数

getUnreadCount()

功能描述

【非离线未读数】打开七鱼页面后,退到自己app页面时,调用该接口获取当前未读消息数量,

示例代码

import { getUnreadCount } from '@ysf/sdk';
getUnreadCount();
console.log('当前未读消息总数: ', total);

监听未读数

onUnread(cb: function)

功能描述

监听未读消息

示例代码

import { onUnread } from '@ysf/sdk';
 onUnread((res: Record<string, Object>) => {
   console.log('当前未读消息总数: ', res.total);
   console.log('新增未读消息: ', res.message);
 });

清空未读消息

clearUnreadCount()

功能描述

清空所有未读消息

示例代码

import { clearUnreadCount } from '@ysf/sdk';
clearUnreadCount(); // 会触发 onunread 回调
console.log('未读消息清空完成!');

沉浸模式兼容设置【deprecated,建议使用下面一种】

configFullScreen(needFullScreen: boolean)

版本要求 >= 1.0.2

功能描述

适配沉浸式模式,防止七鱼页面导航顶在最上面

设置安全距离

setAvoidArea(info: { top?: number; bottom?: number })

版本要求 >= 1.0.10

功能描述

为了适配鸿蒙各种展示姿势,用户可自行设置上下边距

设置旋转模式

configOrientation(orentation:number)

版本要求 >= 1.0.4

功能描述

设置客服页面的旋转模式,默认跟随app

这篇文档有帮助吗?

目录