功能配置API
自定义配置
setCustomConfig
接口描述
配置一些其他的自定义内容
参数说明
setCustomConfig(config: CustomConfig): voidCustomConfig
| 名称 | 类型 | 说明 |
|---|---|---|
| fromTitle | string | 自定义访客咨询来源页的标题,无法自动获取,和 referrer 一起使用 |
| referrer | string | 自定义访客咨询来源页的url,无法自动获取,和 fromTitle 一起使用 |
| customerAvatar | string | 自定义客服头像的url |
| APPbackPop | number | 聊天页面点击返回的时候是否弹出 关闭挽留弹窗0:不弹起1:只弹起关闭挽留弹窗2: 弹起关闭挽留弹窗和满意度评价弹窗(全屏模式不支持) |
| transferToHuman | number | 指定机器人 id 时是否支持转人工,默认1 |
| templateId | number | 指定访客端样式模板 id,id 获取途径见【注1 |
| robotId | number | 指定机器人 id ,id 获取途径见【注2 |
| shortcutTemplateId | number | 机器人常见快捷入口模版id,id 获取途径见【注3】 |
| qtype | number | 机器人常见问题模板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)
功能描述
配置商品、订单卡片,在打开咨询窗口时,还可以带上用户当前正在浏览的商品或订单信息。
商品示例图

订单示例图

参数说明
| 名称 | 类型 | 必须 | 描述 | |
|---|---|---|---|---|
| 通用参数 | cardType | string | 否 | 卡片类型,共三种类型。商品: 0,订单: 1,自定义: 2,推荐填写 |
| sendByUser | number | 否 | 是否由访客手动发送,1为是,其他参数为否 | |
| show | number | 否 | 访客是否可见,1可见,其他参数访客不可见(但客服都是可见的)sendByUser=1 时,show强制为1 | |
| actionText | string | 否 | 发送按钮文案,需设置 sendByUser 生效 | |
| actionTextColor | string | 否 | 发送按钮文案颜色,需设置 sendByUser 生效 | |
| sendProToRobot | number | 否 | 此字段为机器人会话是否发送商品卡片,为1展示机器人阶段发送商品卡片,为0则机器人阶段不发送商品卡片而是人工会话中发送 | |
| intent | string | 否 | 意图名称 | |
| sendKefuOffline | number | 否 | 人工客服不在线进留言的时候是否发送 1为是,0为否,默认为否 | |
| params | object | 否 | 流程参数 | |
| info | string | 否 | 卡片附加信息,信息不展示在前端卡片中,长度限制为100字符,超过自动截断 | |
| agentId | number | 否 | 支持指定Agent接待,不需要调起Agent则参数值上报为空即可。若同时命中intent的小模型意图时,会优先返回小模型答案 | |
| 商品 | picture | string | 是 | 商品的缩略图地址 |
| title | string | 是 | 商品的展示标题 | |
| desc | string | 否 | 商品展示的简要描述 | |
| note | string | 否 | 商品备注,展示位置同商品价格,优先级高于商品价格 | |
| price | string | 否 | 商品的价格(已废弃,请使用 note 替代) | |
| goodsCId | string | 否 | 商品类目ID,长度限制为 100 字符,填写后有助于机器人识别商品和后续业务 | |
| goodsCName | string | 否 | 商品类目名称,长度限制为 10 字,如生鲜食品 | |
| goodsId | string | 否 | 商品ID, 长度限制为 100 字符,商品唯一标识符,填写后有助于机器人识别商品和后续业务,当卡片类型为商品时,推荐填写 | |
| tags | Tag[] | 否 | 订单类消息展示的功能按钮,tag每一项为{"label": "打开七鱼网址","url": "[https://qi.163.com](https://qi.163.com)"},label为按钮的名称,url为打开的链接 | |
| url | string | 否 | 点击商品跳转到的链接地址 | |
| 订单 | picture | string | 是 | 商品的缩略图地址 |
| title | string | 是 | 商品的展示标题 | |
| desc | string | 否 | 商品展示的简要描述 | |
| goodsId | string | 否 | 商品ID, 长度限制为 100 字符,商品唯一标识符,填写后有助于机器人识别商品和后续业务,当卡片类型为商品时,推荐填写 | |
| goodsCId | string | 否 | 商品类目ID,长度限制为 100 字符,填写后有助于机器人识别商品和后续业务 | |
| payMoney | string | 否 | 商品支付的价格 | |
| orderId | string | 是 | 订单的id | |
| orderTime | string | 否 | 下单时间 | |
| orderSku | string | 否 | 订单的sku描述信息 | |
| orderCount | string | 否 | 订单中商品数量 | |
| orderStatus | string | 否 | 订单交易状态 | |
| orderStageType | number | 否 | 订单状态分类 售前阶段:10000 发货前阶段:20000 发货后阶段:30000 售后阶段:40000 | |
| tags | Tag[] | 否 | 订单类消息展示的功能按钮,tag每一项为{"label": "打开七鱼网址","url": "[https://qi.163.com](https://qi.163.com)"},label为按钮的名称,url为打开的链接 | |
| url | string | 否 | 点击商品跳转到的链接地址 | |
| 自定义模版 | template | string | 是 | 模板类型(当前支持"pictureLink"即图片链接模板) |
| picture | string | 是 | 图片地址 | |
| url | string | 否 | 点击图片跳转到的链接地址 |
示例代码
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)
功能描述
配置改回调后,用户点击这个链接后,允许应用自己处理这个点击事件,用于在应用中做自定义响应操作。
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| data | object | url: 访问的链接地址, from: 链接访问的来源模块, extraParam: cb 中可调用的变量参数 |
监听自定义事件
onCustomEvent(cb: function)
功能描述
人工会话下,快捷入口、操作面板中自定义事件点击回调
参数
| 名称 | 类型 | 描述 |
|---|---|---|
| data | object | action: 事件类型[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
这篇文档有帮助吗?