在线工具条对接

概述

七鱼在线工具条是七鱼提供的一款在线客服工具，接入方可以将在线工具条嵌入到自己的网站中，实现在线客服功能。

七鱼侧提供 Api 接口，方便接入方可以和七鱼客服工作台实现交互。

登录获取 SDK 接入地址

在线工具条登录功能可以达到七鱼免登的效果，用于将七鱼客服端作为工具条嵌入第三方网站，或者在第三方认证之后对七鱼进行免登。

功能使用步骤拆解：

步骤 1：向企业服务器端发起异步请求，获取 SDK 地址；
步骤 2：将 SDK 地址作为 Iframe 工具条嵌入第三方页面，或者直接跳转新页签实现免登。

获取 SDK 接入地址

第三方向七鱼请求 SDK 接入地址时，七鱼会执行客服在七鱼的登录事件，并生成含动态口令的 SDK 接入地址返回给第三方。

接口调用及鉴权规则参考通用说明 - 七鱼签名。

curl 请求样例

curl -X POST \
  'https://qiyukf.com/openapi/staff/login?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
  -H 'content-type: application/json;charset=utf-8' \
  -d '{"staffName": "admin"}'

请求参数

Query

参数	是否必填	参数类型	说明
appKey	是	String	企业 appkey
time	是	Integer	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksum	是	String	SHA1(appSecret + md5 + time)，三个参数拼接的字符串进行 SHA1 哈希计算，转化成 16 进制字符（String，小写）

Body

参数	是否必填	参数类型	说明
staffName	是	String	客服在七鱼这边对应的客服名，此处对应的参数值为客服账号

响应参数

接口返回数据为 JSON 格式，最外层参数如下：

参数	参数说明
code	错误码。200 表示设置成功。
result	code 为 200 时，返回值有效。
message	请求错误时，填错误提示信息。

返回示例

如果 code 等于 200 表示客服登录成功，result 内容为 JSON 数据，返回样例如下：

{
  "code": 200,
  "message": "",
  "result": {
    "sdk_url": "https://xxx.qiyukf.com/toolbar/script/get?token=cb1ec3c43089493eb4039945685ebf51",
    "corp_code": "xxx",
    "token": "cb1ec3c43089493eb4039945685ebf51"
  }
}

result 内的参数说明如下：

参数	数据类型	参数说明
sdk_url	String	生成的含动态登录口令的 SDK 接入地址
corp_code	String	登录客服对应的七鱼企业域名
token	String	动态登录口令 token 失效时间和长连接心跳有关系，心跳超时时间 270 秒（4.5 分钟）

错误码含义参考通用说明 - 通用错误码列表。

监听新消息提醒

背景

浏览器的系统消息使用的是原生的 Notification api, 工具条是跨域的 iframe 内嵌到浏览器页面内，因此内部直接调用 Notification 会不生效，导致工具条没有系统通知的功能。

针对 iframe 内嵌的工具条场景，需要七鱼侧通过 postMessage 的方式通知接入方，接入方再调用 Notification 接口弹出系统通知。

对接方案

七鱼侧的业务代码内在需要提示系统消息的地方全部对外使用 postMessage 的方式通讯

const config = {
  body: message,
  id: sessionId,
  icon: ICON_URL,
  rurl: `${kefuPathPrefix}/?id=${sessionId}`,
};

window.parent.postMessage({
  method: 'showNotification',
  params: {
    title: title,
    config: config
  }
}, '*');

工具条的客户接入方监听内部的消息，并识别对应的方法是 showNotification 就直接调用系统通知弹出来即可，并且需要自行实现提示音播放

以下实例代码处理了监听通知过来之后弹系统消息、系统消息排队、超时关闭、点击关闭、以及点击消息窗口获焦的逻辑，可作为接入参考

// 通知音频文件
let audio = null;
const audioUrl = ''; // TODO: 用户自行补充，通知提示音频

// 请注意，音频自动播放需要用户进行一次交互
const appendNotifyAudio = () => {
  if (audio) {
    return;
  }
  audio = document.createElement('audio');
  audio.src = audioUrl;
  audio.preload = 'auto';
  document.body.appendChild(audio);
};

// 添加音频节点
appendNotifyAudio();

// 播放音频
const playVoice = () => {
  if (audio) {
    audio.play();
  }
};

// 监听客服工作台 postMessage 事件
window.addEventListener('message', (evt) => {
  const data = evt.data;
  const nQueue = [];
  if (data?.method === 'showNotification') {

    // 播放提示音
    playVoice();

    const cache = {
      id: data.config.id,
      notify: new Notification(data.title, data.config),
    };

    // remove first notify
    if (nQueue.length >= 3) {
      const cch = nQueue.shift();
      if (cch) {
        cch.notify.close();
      }
    }

    nQueue.push(cache);

    cache.timer = window.setTimeout(() => {
      cache.notify.close();
    }, 20000);

    cache.notify.onclose = () => {
      window.clearTimeout(cache.timer);
      const index = nQueue.indexOf(cache);
      if (index >= 0) {
        nQueue.splice(index, 1);
      }
    };

    cache.notify.onclick = () => {
      window.focus();
      cache.notify.close();
    };
  }
});

监听文件预览

背景

工具条场景，只能在七鱼窗口内做预览，个别场景下会比较小，客户可以配置自己实现相关文件查看功能。

如需开启功能，请联系七鱼客服人员进行配置

对接协议

// 文件信息
type ViewItem = {
  name: string; // 文件名称
  url: string; // 文件地址
};

// postMessage 消息格式
type EventData = {
  type: 'preview'; // 消息类型
  content: {
    type: 'image' | 'video' | 'pdf' | 'txt'; // 预览文件类型
    name: string;  // 预览文件名称
    url: string; // 预览文件地址
    index?: number; // 上下文中有多张图片时，当前图片索引
    items?: ViewItem[]; // 上下文中所有图片地址
  }
}

对接示例

window.addEventListener('message', (evt) => {
  const data = evt.data;
  if (data?.type === 'preview') {
    // TODO: 自行实现文件查看器
  }
});

监听会话协助事件

请注意触发该事件时，同时会触发 showNotification 事件

背景

需要根据【会话协助】事件，处理一些额外的业务逻辑

对接协议

type EventData = {
  type: 'receiveAssistSession';
  content: {
    assistId: number; // 被邀请协助客服id
    remarks: string; // 备注
    sessionId: number; // 会话id
    staffId: number; // 协助发起客服id
    staffName: string; // 协助发起客服名称
    timestamp: number; // 时间戳
  }
}

对接示例

window.addEventListener('message', (evt) => {
  const data = evt.data;
  if (data?.type === 'receiveAssistSession') {
    // TODO: 处理自定义逻辑
  }
});

监听会话转接事件

请注意触发该事件时，同时会触发 showNotification 事件

仅开启设置 > 会话流程 > 会话转接 > 转接确认，才会触发此事件

背景

需要根据【会话转接】事件，处理一些额外的业务逻辑

对接协议

type EventData = {
  type: 'receiveTransferSession';
  content: {
    sessionid: number; // 会话id
    staffid: number; // 转接发起客服id
    staffname: string; // 转接发起客服名称
    transferid: number; // 被邀请转接客服id
    userName: string; // 用户名称
    vipLevel: number; // vip等级
    remarks: string; // 备注
    timestamp: number; // 创建时间
  }
}

对接示例

window.addEventListener('message', (evt) => {
  const data = evt.data;
  if (data?.type === 'receiveTransferSession') {
    // TODO: 处理自定义逻辑
  }
});

监听客服登出

背景

需要根据【客服登出】事件，处理一些额外的业务逻辑

对接协议

type EventData = {
  type: 'logout';
}

监听会话关闭

背景

需要根据【会话关闭】事件，处理一些额外的业务逻辑

对接协议

// 关闭类型枚举，抛出去给工具条使用的
type CLOSE_TYPE = 
  'staffClose' // 客服关闭
  | 'userLeave' // 用户离开
  | 'autoClose' // 用户不说话 自动关闭了
  | 'robotTrans' // 机器人会话转接到人工
  | 'staffLeave' // 客服离开
  | 'staffTrans' // 客服主动将会话转出
  | 'staffTakeover' // 管理员强势接管会话，或访客再次申请其他客服
  | 'userClose' // 访客关闭
};

type EventData = {
  type: 'sessionClose';
  from: 'qiyu';
  sessionId: number;
  userId: number,
  closeReason: {
    code: number,
    type: CLOSE_TYPE,
  },
}

监听新会话进入

背景

需要根据【新会话】事件，处理一些额外的业务逻辑

对接协议

type EventData = {
  type: 'sessionStart';
  from: 'qiyu';
  sessionId: number;
  userId: number;
  fromTitle: string;
  userAgent: string; 
}

监听清除会话

注意：仅客服工作台经典模式触发

背景

需要根据【清除会话】事件，处理一些额外的业务逻辑

对接协议

enum SessionType {
  ONLINE = 0, // 在线
  LEAVE = 1, // 已离线
  END = 2, // 已结束
  QUEUE = 3 // 排队中
}

type EventData = {
  type: 'sessionClear';
  time: number;
  sessionIds: number[];
  sessionType: SessionType;
  staff: {
    staffId: number;
    userName: string;
  }
}

监听会话切换

背景

需要根据【会话切换】事件，处理一些额外的业务逻辑

对接协议

type EventData = {
  type: 'sessionSwitch';
  sessionId: number; // 会话Id
  userId: number; // 访客userId
  fromTitle: string; // 访客来源页标题
  userAgent: string; // 访客浏览器信息
}

调用会话结束、清除

背景

希望在业务页面调用 postMessage 通知七鱼工作台结束、清除会话

对接协议

iframe.contentWindow.postMessage({
  method: 'closeSession',
  params: {
    type: 'close', // close: 结束会话、clear: 清除会话、closeAndClear: 结束并清除会话
    id: 100000626355    
  }
}， '*')

在线工具条对接

目录