网易七鱼Web开发指南

WEB-SDK概要

七鱼客服SDK可以帮助第三方网站及应用快速构建一个完善的客服系统生态圈,SDK提供较为完善的客服应用功能,及简洁的API接口。

SDK提供如下扩展功能:

以下所有接入代码的例子都可以在这里下载。接入Demo

Web接入方案

基本接入配置

  1. 管理端获取接入代码

    管理端-设置-网站接入-接入及开关-接入代码。

  2. 完整页面实例展示


    <!DOCTYPE html>
    <html>
        <head>
            <title>在线客服</title>
            <meta charset="utf-8"/>
        </head>
        <body>
            <!-- YOUR CODE HERE -->
            <script src="https://qiyukf.com/script/044865c94981c048609d5c94c1ae9c6d.js" charset="UTF-8"></script>
        </body>
    </html>
  1. 管理端可以实现如下入口配置:

    • 三种访客接入模式
    • 自定义配置访客入口
    • 自定义访客端皮肤

企业CRM对接

企业可以通过请求脚本时增加企业配置信息,以便在客服系统中将会话与企业产品中的用户关联起来,如以下方式

 <script src="https://qiyukf.com/script/[APPKEY].js" charset="UTF-8"></script>

 <script>
     ysf.config({
       uid:"1442286211167",  // 企业用户Id
       name:'test',          // 企业用户名称
       email:'test@163.com', // 企业邮箱
       mobile:'13888888888'  // 企业电话
   });
 </script>

企业用户账号的切换

企业对接的情况下, 企业需要切换账号时, 接入七鱼的第三应用需要调用 ysf.logoff() 函数登出。

企业基础信息

使用SDK时可以配置一些企业产品相关的用户信息,以便在客服后台可以正确识别出对应的用户,七鱼客服WEB SDK提供企业可以设置以下信息:

参数 类型 描述
uid String 可选,用户在企业产品中的标识,便于后续客服系统中查看该用户在产品中的相关信息,不传表示匿名用户
name String 可选,用户在企业产品中的名称,便于后续客服系统中查看该用户在产品中的相关信息
email String 可选,用户在企业产品中的邮箱,便于后续客服系统中查看该用户在产品中的相关信息
mobile String 可选,用户在企业产品中的手机,便于后续客服系统中查看该用户在产品中的相关信息
data String 可选,用户在企业中的其他详细信息,JSON字符串,不可以通过脚本参数输入,只能通过 ysf.config 接口配置

企业扩展信息

扩展信息字段data用一个数组的 JSON 字符串描述用户的详细信息,数组中每个元素代表一个数据项。数据项以(key, value)对的形式为基础,增加了额外的字段以控制显示样式。数据项定义如下:

字段 类型 必须 说明
key String 数据项的名称,用于区别不同的数据。其中real_name、mobile_phone、email为保留字段,分别对应客服工作台用户信息中的“姓名”、“手机”、“邮箱”这三项数据。保留关键字对应的数据项中,index、label属性将无效,其显示顺序及名称由网易七鱼系统指定。
value Mixed 该数据显示的值,类型不做限定,根据实际需要进行设定。
label String 该项数据显示的名称。
index Int 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址。
hidden Boolean 仅对mobile_phone、email两个保留字段有效,表示是否隐藏对应的数据项,true为隐藏,false为不隐藏。若不指定,默认为false不隐藏。

轻量CRM接入方案

接入代码:


    ysf.config({
        uid:"1442286211167",
        name:'test',
        email:'test@163.com',
        mobile:'13888888888'
    });

扩展CRM接入方案

接入代码:


    ysf.config({
       uid:"1442286211167",
       data:JSON.stringify([
           {"key":"real_name", "value":"土豪"},
           {"key":"mobile_phone", "hidden":true},
           {"key":"email", "value":"13800000000@163.com"},
           {"index":0, "key":"account", "label":"账号", "value":"zhangsan" , "href":"http://example.domain/user/zhangsan"},
           {"index":1, "key":"sex", "label":"性别", "value":"先生"},
           {"index":5, "key":"reg_date", "label":"注册日期", "value":"2015-11-16"},
           {"index":6, "key":"last_login", "label":"上次登录时间", "value":"2015-12-22 15:38:54"}
       ])
    });

接口CRM对接

企业 CRM 接口由客户企业提供并实现,网易七鱼系统将在必要的时候调用特定的接口,并将接口返回的数据以约定的样式显示在客服工作界面。 特别要注意企业需要进行 服务器跨域配置, 具体详情见: 企业信息对接

商品链接

发起会话前,企业可以将用户正在查看的商品信息发送给客服,以便客服在后台及时预判访客需要咨询的内容。


    ysf.product({
         show : 1, // 1为打开, 其他参数为隐藏(包括非零元素)
         title : '标题',
         desc : '商品描述',
         picture : '商品图片地址',
         note : '备注',
         url : '跳转链接'
    })

注: show -参数用于控制访客端商品链接的是否显示;对于客服端,只要接入就一定会显示商品链接信息

访客分流

网易七鱼客服系统默认会按照智能方式分配客服, 如果想让访客分配给指定的客服组或者客服,则需要使用访客分流功能

如何查找客服信息

在管理端 -> 设置 -> 访客分流 -> ID查询下面, 可以查找到相应的客服id和客服组id。 可以直接复制链接地址接入

SDK方式

接入代码:


    ysf.config({
        uid:"1442286211167",
        name:'test',
        email:'test@163.com',
        mobile:'13888888888',
        staffid:'123', // 客服id
        groupid: '123' // 客服组id
    });

访客端自定义

七鱼客服的系统默认入口是放在页面左下角。 如果企业需要自定义入口, 可以进行如下操作步骤:

  1. 管理中心 - 接入设置 - 网站接入 - 访客开关, 设置 停用
  2. 企业开发者设置入口图片,样式
  3. 在入口的点击事件时调用 WEB-SDK 的 ysf.open() API接口

未读消息

企业需要对未读消息进行些额外的操作, 七鱼暴露 unread 事件读取未读消息,具体使用如下:


    ysf.on({
        unread : function(msg){
            if(msg.total){
                // 处理逻辑
            }
        }

    });

VIP接入支持

企业需要对不同级别的访客进行接待区分为VIP客户和普通客户;七鱼支持VIP客服的接入,VIP可区分等级, 持上限为10级。

接入代码

        ysf.config({
            uid : 'user',
            level : 1 // vip级别
        })

常见问题

访客进入咨询时,如果进入了机器人会话,企业可以通过设置常见问题,将一些用户可能需要问的问题首先发送给用户。通过高级自定义配置,可以给不同页面中的不同咨询入口设置不同的常见问题。

查询问题模板id

在管理端 -> 设置 -> 机器人 -> 常见问题设置 -> 设置常见问题模板,可以查找到企业的常见问题模板及其id。

接入代码

    ysf.on({
        'onload': function(){
            ysf.config({
               uid:"201609051809",
               name:'接入',
               email:'test@163.com',
               mobile:'13888888888',
               qtype: 1056         //常见问题模板id
           });
        }
    })

接入演示

常见问题

API接口列表

接口名称 接口说明
ysf.config 用户信息配置接口
ysf.logoff 用户登出需要调用的接口
ysf.product 商品链接接口
ysf.on 事件监听接口,用于onload, unread功能接口
ysf.open 打开SDK入口