网易七鱼企业信息对接开发指南

简介

概述

网易七鱼系统可以与企业 CRM 系统进行对接。

对接分轻量对接接口对接两种方式。

轻量对接的数据由企业产品客户端(或网站)将数据提交给网易七鱼系统,数据将展现在客服工作界面的当前会话和历史会话的“用户资料”标签下。接口对接的数据由企业接口提供,由网易七鱼系统客服端调用,数据将展现在客服工作界面的当前会话和历史会话的“更多信息”标签下。

轻量对接和接口对接的具体说明,请分别阅读轻量 CRM 对接 CRM 接口对接章节。两种对接方式的对比,请阅读对接方式对比与建议章节。

文档约定

访客:指使用企业产品的用户,例如使用企业 App 产品的用户,或访问企业网站或 Web 产品的用户。

企业接口:指接口对接方式下,企业提供给网易七鱼系统的 HTTP 接口。

客服工作台客服工作界面:都是指网易七鱼系统提供给客服使用的工作环境,即客服登录网易七鱼系统后使用的 Web 界面。

Web SDK:指网易七鱼系统提供的 Web 端开发工具包,供企业将网易七鱼功能嵌入到官网或 Web 产品中。主要包含一个在线获取的 JS 文件。

iOS SDK:指网易七鱼系统提供的 iOS 平台开发工具包,供企业将网易七鱼功能嵌入到 iOS 产品中。主要包含一个 .a 静态库,和一系列依赖的头文件、资源文件。

Android SDK:指网易七鱼系统提供的 Android 平台开发工具包,供企业将网易七鱼功能嵌入到 Android 产品中。主要包含多个 .jar 包,和一系列依赖的资源文件。

JSON:企业 CRM 系统与网易七鱼系统对接,数据传输时使用 JSON 格式。多数情况下数据都保存在一个数组中,数组中一个元素表示一个数据项。数据项包含的字段,有些是必选的,有些是可选的,请仔细阅读每个接口的数据定义。参考:JSON介绍JSON在线校验工具

轻量 CRM  对接

轻量 CRM 对接是指通过 Web / iOS / Android SDK 发起会话时,可以将访客的信息作为参数传递给网易七鱼系统。

Web SDK 调用

调用ysf.config()时,将包含用户信息的 JSON 传递给网易七鱼系统。

ysf.config({
    "uid":"zhangsan",
    "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"}
    ])
});

注意:data字段的内容需使用JSON.stringify()进行序列化。为保持良好的兼容性,若要支持较低版本的浏览器(如IE8及更低版本)则需引入第三方JSON库,如 JSON3

iOS SDK 调用

创建一个QYUserInfo实例,将包含用户信息的 JSON 字符串填充到QYUserInfo.data。调用setUserInfo时将此QYUserInfo实例作为参数传递给网易七鱼 SDK。

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
userInfo.data = @"[{\"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\"}]";

[[QYSDK sharedSDK] setUserInfo:userInfo];

Android SDK 调用

创建一个YSFUserInfo实例,将包含用户信息的 JSON 字符串填充到YSFUserInfo.data。调用Unicorn.setUserInfo()时将此YSFUserInfo实例作为参数传递给网易七鱼 SDK。

YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId = "uid";
userInfo.data = "[{\"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\"}]";

Unicorn.setUserInfo(userInfo);

参数说明

网易七鱼系统轻量对接中的参数,不论是 Web SDK、iOS SDK、还是 Android SDK,都由一个用户唯一性标识uid和一个表示用户信息的 JSON 数组data组成。

在 Web SDK 中uiddata都直接出现在 JSON 中。iOS SDK 和 Android SDK 中,各定义了一个保存用户信息的结构体:iOS 中为QYUserInfo,Android 中为YSFUserInfo。iOS SDK 中,QYUserInfo.userId成员为用户唯一性标识字符串,QYUserInfo.data成员为表示用户信息的 JSON 字符串。Android SDK 中,YSFUserInfo.userId成员为用户唯一性标识字符串,YSFUserInfo.data成员为表示用户信息的 JSON 字符串。

下文参数说明中的uid分别对应 Web SDK 中的 JSON 字段 uid、iOS SDK 中的QYUserInfo.userId、Android SDK 中的YSFUserInfo.userIddata分别对应 Web SDK 中的 JSON 字段 data、iOS SDK 中的QYUserInfo.data、Android SDK 中的YSFUserInfo.data

参数
类型 必须 说明
uid String 用户唯一性标识。
data Array / String 用一个数组(或表示 JSON 数组的字符串),表示要显示在客服端的扩展信息。

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

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

注意: real_namemobile_phoneemail三个保留字段的特别说明:

注意: 提交的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高,应当在提交时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

企业 CRM 接口对接

概要

企业 CRM 接口由客户企业提供并实现,网易七鱼系统将在必要的时候调用特定的接口,并将接口返回的数据以约定的样式显示在客服工作界面上。

企业实现这些接口,可以为网易七鱼系统提供用户信息、订单信息等 CRM 数据,以便客服在工作时方便地获得丰富的信息,更好的提供服务。

企业接口为一系列 HTTP (或 HTTPS)接口,由网易七鱼系统发起调用。网易七鱼系统与企业 CRM 系统通过这些接口进行数据交换,数据通常以 JSON 格式展现。即:

数据格式请仔细阅读每个接口的说明。

为保证数据的安全、并考虑一定的扩展性,企业需提前给网易七鱼系统分配appidappsecret用于接口调用时的认证。认证方式见下。

本文档中的接口地址都为相对路径。接口完整的 URL 需要在网易七鱼管理端进行设置。

跨域访问

获取 token验证用户身份接口外,其他接口都由网易七鱼系统客服端前端发起调用,所以这些接口需要支持跨域访问。接口的响应头域(Header)中需要添加以下参数:

Access-Control-Allow-Headers: origin, x-csrftoken, content-type, accept, x-auth-code, X-App-Id, X-Token
Access-Control-Allow-Method: POST, GET, OPTIONS
Access-Control-Allow-Origin: http://xxx.qiyukf.com

其中Access-Control-Allow-Origin中的xxx应该替换为企业在网易七鱼系统上申请的二级域名。

更多信息请参考 W3C Recommendation: Cross-Origin Resource Sharing

接口认证方式

接口认证方式有两种可选:

特别地,若企业不提供获取 token 的接口,则接口必须为 HTTPS 协议。(现在暂不限制)

认证参数传递方式也有两种可选:

获取 token

GET /get_token

与其他接口不同,获取 token 接口为 GET 请求。该接口由网易七鱼系统后端服务器调用,并根据返回的有效期决定调用时机。

请求

参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid
appsecret String 企业分配给网易七鱼系统的 appsecret

响应

接口应该返回一段包含 token 和有效期的 JSON。

{
    "rlt": 0,
    "token": "qiyukf_security_token",
    "expires": 7200000
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
token String 后续接口调用时使用的有效 token。
expires Int 表示此token离过期剩余的 毫秒数(非过期时间戳)。若不指定、或小于等于零,则默认为 2 小时。token失效后,其他接口应返回错误码2

获取用户信息

POST /get_user_info

网易七鱼系统在需要获取访客详细信息时,会调用该接口。

返回的数据将显示在“当前会话”中右侧用户资料区的“更多信息”标签页下,以及“历史会话”中右侧会话详情区的“更多信息”标签页下。

用户的唯一性标识会被作为请求内容 POST 到该接口。

请求

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan"
}
参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid。
token String 当前有效的 token。
userid String 用户的唯一性标识。

注意:userid来源于用户发起会话时,调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

响应

接口应该返回一段包含用户数据的 JSON。

{
    "rlt": 0,
    "data": [
        {"index": 0, "key": "account", "label": "账号", "value": "zhangsan"},
        {"index": 1, "key": "name", "label": "姓名", "value": "土豪", "edit": true, "map": "real_name"},
        {"index": 2, "key": "phone", "label": "手机", "value": "13800000000", "edit": true, "map": "mobile_phone"},
        {"index": 3, "key": "email", "label": "EMail", "value": "13800000000@163.com", "edit": true, "map": "email"}
    ],
    "modify_cb": "url"
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
data Array 用一个数组表示用户详细信息的数据。
modify_cb String 如果企业希望客服可以在网易七鱼系统中更新客户的信息,则在此提供一个接口的地址,用于客户信息修改后回调。接口定义见下。

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

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。特别地,如果该数据可编辑(见edit字段说明),key将作为请求的内容提交给回调接口。
value Mixed 该数据显示的值,类型不做限定,根据实际需要进行设定。
label String 该项数据显示的名称。
index Int 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
edit Boolean 表示该项数据是否可编辑,true为可编辑,false为不可编辑。可编辑时该项数据的值将显示在一个输入框内,内容被编辑后将调用modify_cb接口提交更新。
map String 表明该项数据是否与网易七鱼系统中固定的数据项有映射关系。如真实姓名为real_name,手机号为mobile_phone,电子邮箱为email。如果一个数据项指定了正确的map值,则该数据也会同步显示在“当前会话”中右侧用户资料区的“用户资料”标签页下对应的项目中,以及“历史会话”中右侧会话详情区的“用户资料”标签页下对应的项目中。

注意: 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高,应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

更新用户信息

POST /[modify_cb]

用户的唯一性标识和被修改的信息会被作为请求内容 POST 到该接口。

接口地址由获取用户信息接口/get_user_info返回的modify_cb的内容指定。

请求

{
    "appid":"qiyukf",
    "token":"qiyukf_security_token",
    "userid":"zhangsan",
    "data":[
        {"key":"name", "value":"张三"},
        {"key":"phone", "value":"1397777777X"}
    ]
}
参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid。
token String 当前有效的 token。
userid String 用户的唯一性标识。
data Array 用一个数组表示修改的用户信息数据。

注意:userid来源于用户发起会话时,调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

其中data用一个数组描述提交修改的数据,数组的每个元素表示一个数据项。数据项以<key, value>对的形表示:

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。key的值来源于获取用户信息/get_user_info接口返回的信息中对应数据项的key
value String 该数据修改后的值。都视为字符串进行传输。

响应

接口应该返回一段包含用户信息更新结果的 JSON。

{
    "rlt":0,
    "data":[
        {
            "key":"name",
            "msg":"名字太长了。"
        },
        {
            "key":"phone",
            "msg":"手机号格式错误。"
        }
    ]
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
data Array rlt不为0时,用一个数组表示每项数据修改失败的原因提示。

其中data字段用一个数组描述修改失败的提示信息,数组中每个元素代表一个数据项。数据项定义如下:

字段 类型 必须 说明
key String 数据项的名称,用于区别不同的数据。对应请求中数据项的key
msg String 该项数据修改失败的错误提示。

获取订单信息

POST /get_order

网易七鱼系统在调用获取访客详细信息接口/get_user_info时,会调用该接口。该接口可用于电商行业订单类信息,也可以用于金融行业交易类信息。

返回的数据将显示在“当前会话”中右侧用户资料区的“更多信息”标签页下,以及“历史会话”中右侧会话详情区的“更多信息”标签页下。

在这两个标签下,用户的订单信息会显示在用户详细信息(/get_user_info接口返回的数据)之下。

用户的唯一性标识会被作为请求内容 POST 到该接口。

请求

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan"
    "count": 10,
    "from": 0
}
参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid。
token String 当前有效的 token。
userid String 用户的唯一性标识。
count Int 请求返回订单的最大数量。与from配合使用实现分页。
from Int 请求返回订单列表的偏移量,与count配合使用实现分页。

注意:userid来源于用户发起会话时,调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。

响应

接口应该返回包含指定用户订单类数据列表的一段 JSON。

{
    "rlt": 0,
    "count": 99,
    "orders": [
        {
            "index": 0,
            "blocks": [
                {
                    "index": 0,
                    "is_title": true,
                    "data": [
                        { "index": 0, "key": "orderid",  "label": "订单号", "value": "00001", "href": "url"}
                    ]
                },
                {
                    "index": 1,
                    "data": [
                        {"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
                        {"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"}
                    ]
                },
                {
                    "index": 2,
                    "data": [
                        {"index": 0, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险" , "href": "url"},
                        {"index": 1, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"},
                        {"index": 2, "key": "revenue_amount", "label": "累计收益", "value": "2.00元" }
                    ]
                }
            ]
        },
        {}
    ]
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
count Int 表示该用户订单类数据的条目总数,而非此次请求返回的订单数量。用于控制分页。
orders Array 用一个数组表示用户订单列表的数据。

订单列表有多层数据嵌套:

以下为orders中每个订单的数据定义:

字段
类型 必须 说明
index Int 用于排序,显示订单列表时订单按index值升序排列;不设定index的订单将排在后面;index相同或未设定的订单将按照其在 JSON 中出现的顺序排列。
blocks Array 用一个数组表示该订单包含的区块。

以下为blocks中每个区块的数据定义:

字段
类型 必须 说明
index Int 用于排序,显示订单时区块按index值升序排列;不设定index的区块将排在后面;index相同或未设定的区块将按照其在 JSON 中出现的顺序排列。
data Array 用一个数组表示该区块包含的数据。
is_title Boolean 表示该区块是否作为该订单的标题行,true表示是标题行,false表示不是标题行。当一个区块是标题行时,它将会以订单标题的样式进行显示;而且点击该区块时,该订单会有展开/收起表现。

以下为data中每个数据项的定义:

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。
value Mixed 该数据显示的值,类型不做限定,根据实际需要进行设定。
label String 该项数据显示的名称。
index Int 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址。

注意: 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高,应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

示意图,敬请期待

获取验证表单

网易七鱼系统提供客服验证访客身份的功能。客服在需要确认访客身份时,发起身份验证请求,访客端即可显示预设的表单。访客填写表单后提交验证,而填写的信息并不会被客服看到。客服将直接收到访客身份验证的结果。

验证访客身份的功能在很多场景下非常必要,比如:

身份验证的接口分两部分:

POST /get_verify_form

获取验证表单的接口,用于企业告诉网易七鱼系统哪些信息可以用于访客身份验证,以及验证的接口地址是什么。

请求

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token"
}
参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid。
token String 当前有效的 token。

响应

接口应该返回包含所有可供客服使用的验证表单的列表。

{
    "rlt":0,
    "forms":[
        {
            "index":0,
            "form_name":"verify_id",
            "caption":"请填写以下信息,以便继续为您服务",
            "data":[
                {
                    "index":0,
                    "key":"id_no",
                    "label":"证件号"
                },
                {
                    "index":1,
                    "key":"bank_acc",
                    "label":"银行卡号",
                    "hidden":true
                }
            ],
            "verify_cb":"url",
            "tip":"请准确填写您注册时使用的证件号码,和您账户绑定的银行卡号。这些信息将通过安全连接进行传输,自动验证,不会被任何人看到。"
        },
        {
            "index":1,
            "form_name":"verify_mobile",
            "caption":"表单的标题",
            "data":[
                {
                    "key":"mobile",
                    "label":"手机号"
                }
            ],
            "verify_cb":"url",
            "tip":"描述表单填写规则,或其他说明"
        }
    ]
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
forms Array 用一个数组表示客服可以发起的验证表单列表。

其中forms字段用一个数组表示客服可以发起的验证表单的列表,数组中每一项元素描述一个表单,每个表单的数据项定义如下:

字段
类型 必须 说明
form_name String 表单的名称,用于区别不同的表单。当表单数据被提交验证时,form_name会同数据一起提交,以便验证接口确认数据来源于哪个表单。特别是当不同表单的verify_cb验证地址相同时,form_name格外重要。
data Array 用一个数组表示该表单包含的数据。
verify_cb String 此表单的验证接口地址
index Int 用于排序,客服端显示验证表单列表时按index值升序排列;不设定index的表单将排在后面;index相同或未设定的表单将按照其在 JSON 中出现的顺序排列。
caption String 验证表单在访客段显示时的标题。若不设定,则使用默认标题。
tip String 设定表单的说明或填写规则,会显示在表单的下方。

其中data字段用一个数组描述表单所验证的数据项,每个数据项的定义如下:

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。
label String 该项数据显示的名称。
index Int 用于排序,显示表单时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
hidden Boolean 表示该项数据是否为密码域,true表示是密码域,false表示不是密码域。当一项数据为密码域时,用户输入的内容会被*·代替。不设定hidden时数据项默认不是密码域。

验证用户身份

POST [``verify_cb``]

访客填写完身份验证表单,并提交数据后,网易七鱼系统会将用户填写的内容,提交给企业提供的验证用户身份接口进行身份验证。

验证用户身份接口的地址,由获取验证表单接口/get_verify_form返回的verify_cb的内容指定。

请求

{
    "appid":"qiyukf",
    "token":"qiyukf_security_token",
    "form_name":"verify_id",
    "userid":"zhangsan",
    "data":[
        {
            "key":"id_no",
            "value":"330108000000009999"
        },
        {
            "key":"bank_acc",
            "value":"628888888888888"
        }
    ]
}
参数 类型 必须 说明
appid String 企业分配给网易七鱼系统的 appid。
token String 当前有效的 token。
form_name String 表单的名称,来源于 /get_verify_form接口返回的form_name字段,由客服推送给访客进行身份验证的表单决定。
userid String 用户的唯一性标识。
data Array 用一个数组表示提交验证的数据。

其中data用一个数组包含提交验证的数据,数组的每个元素表示一个数据项,数据项定义如下:

字段 类型 必须 说明
key String 数据项的名称,用于区别不同的数据。来源于/get_verify_form接口返回的表单中数据项的key字段。
value String 该数据的值,是访客输入的内容。都视为字符串进行传输。

注意:userid来源于用户发起会话时,调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。一般来讲,用户只有在企业应用中登录后,才有这个userid。也就是说,在用户未登录状态下,客服发起访客身份验证,验证请求中可能没有userid这个字段。验证接口需要充分考虑到这种情况,以确定在验证访客身份时是否会参考userid的值。但不论是否会用到,网易七鱼系统总会尽量在请求中带上userid信息。

响应

接口应该返回访客身份验证的结果,可以同时返回访客更多的信息。

{
    "rlt":0,
    "verify_rlt":true,
    "userid":"zhangsan",
    "data":[
        {"index":0, "key":"name", "label":"姓名", "value":"张三"},
        {"index":1, "key":"real_name_auth", "label":"实名认证", "value":"是"},
        {"index":2, "key":"bank_acc", "label":"绑定银行卡", "value":"************4174"},
        {"index":3, "key":"cash", "label":"余额", "value":"¥8*,***.**"}
    ]
}
字段
类型 必须 说明
rlt Int / String 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述,见Appendix I节。
verify_rlt Boolean 表明访客填写的信息是否通过了验证,true表示通过,false表示不通过。这个结果会在客服端当前会话内容中显示,提醒客服。
userid String verify_rlttrue时,可以返回该用户对应的userid。若返回userid,且企业提供了获取用户信息/get_user_info接口、获取订单信息/get_order接口,则网易七鱼系统在收到此次响应时会以此userid作为请求参数,调用这些接口,并将获取到的用户信息展示在当前会话右侧用户资料区的“更多信息”标签页下。
data Array verify_rlttrue时,可以返回该用户的一些信息,这些信息将直接在客服端当前会话内容中显示。用一个数组表示这些信息所包含的数据。

其中data字段用一个数组描述用户的信息,数组中每个元素代表一个数据项。数据项的定义与获取用户信息/get_user_info接口返回的data定义一致,但不包含editmap字段:

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。
value Mixed 该数据显示的值,类型不做限定,根据实际需要进行设定。
label String 该项数据显示的名称。
index Int 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。

对接方式对比与建议

轻量对接与接口对接的比较。场景、开发难度、数据隔离。

建议不同的企业、团队,用不同的对接方式。

轻量对接方式与接口对接方式,都是为了给客服在服务过程中提供丰富的访客信息,从而提高服务质量与工作效率。然而两种对接方式在使用场景与实现方式方面各有不同,以下对两种对接方式进行对比。

对比角度
轻量对接 接口对接
数据来源 发起会话时,客户端通过 SDK 提交。 企业提供的 HTTP 接口。
调用方式 客户端通过 SDK 将数据提交给网易七鱼系统服务器,客服工作台向网易七鱼服务器发起请求。 客服工作台直接向企业提供的 HTTP 接口发起请求。
数据存储 访客数据加密后保存在网易七鱼系统。 客服工作台前端直接发起请求,数据不经网易七鱼服务器,完全隔离。
功能 展现自定义访客信息:√ 展现订单类数据:× 数据与企业 CRM 同步:× 访客信息验证:× 展现自定义访客信息:√ 展现订单类数据:√ 数据与企业 CRM 同步:√ 访客信息验证:√
展现位置 当前会话和历史会话的“用户资料”标签下 。 当前会话和历史会话的“更多信息”标签下。
开发难度 低。 只要客户端有访客的相关数据,就可以按约定拼出 JSON 提交。 中。 需要开发一套 HTTP 接口,与企业 CRM 数据库对接。若已有类似接口,则非常容易进行对接。
开发成本 低。 可快速实现。 无特别要求。 中。 需要一定的人力进行开发。 需支持跨域
适用场景 产品规模较小; 产品发展初期; 团队规模较小; 技术人力紧张; 企业 CRM 尚不完善; 访客数据要求一般不需要订单、交易类信息。 产品规模中大; 产品发展成熟期; 团队规模中大; 技术人力有一定支持; 企业 CRM 较完善; 访客数据要求需要订单、交易类信息。

Appendix I 错误码

所有对接接口rlt错误码保留值定义如下:

其他情况,可根据企业业务逻辑自行设定错误码,仅供显示用。

有关认证方式的说明,请参考接口认证方式章节。

所有错误码,包括保留的错误码,均可使用整形或字符串。即:

{
    "rlt": 0
}
{
    "rlt": "0"
}

两种表示方法是等价的。

当接口返回的rlt字段值不为0时,可以在返回的内容中设置一个msg字段,提供用于显示的错误信息。

七鱼用户认证机制

概要

术语

简介

第三方接入七鱼后,可以上报uid,用以访问或关联用户在第三方的真实业务数据。本文描述了七鱼对uid进行身份认证的方案。适用于对uid真实性要求较高的场景。

方案

认证过程

  1. 第三方提供一个生成随机授权码authToken授权接口authToken生成后需要暂存在第三方服务器端,供之后的uid校验使用;
  2. 申请客服或上报CRM信息请求时,先调用上面接口,获取随机授权码authToken,并将其传递给七鱼;
  3. 七鱼前端将获取到的authTokenuid作为参数传递到七鱼服务器端;
  4. 七鱼服务器收到请求后,携带authTokenuid,调用第三方认证接口进行校验;
  5. 第三方将收到的authToken与本地暂存的authToken进行比较,看是否一致,并返回校验结果;
  6. 如果authTokenuid校验失败,七鱼服务器会忽略请求,并返回失败信息到前端页面。

实施流程

  1. 第三方知会七鱼需开启用户认证,并协调约定开启时间;
  2. 第三方在约定的开启之前准备好认证接口,将线上接口地址提交给七鱼,并与七鱼做好联调工作;
  3. 第三方使用支持的SDK,并按下文中代码示例完成authToken的设置工作。

授权接口

生成随机授权码authToken的接口。该接口可以由第三方自己调用,也可以将其url地址提供给七鱼,由七鱼代理获取。

如果该接口由第三方自己调用,需要第三方自己保证生成的authToken在使用时不会过期,如定期将新生成的authToken通过七鱼SDK接口函数传递给七鱼。七鱼不关心该接口的定义规则。

如果该接口由七鱼调用,则第三方不需要关心authToken的过期问题,但接口必须遵循以下定义规范:

调用说明:

响应:

{"code":200,"token":false}

响应字段:

字段 含义
code 响应码,200表示生成authToken成功
token 新生成的authToken

认证接口

七鱼服务端收到相关请求后,会携带认证信息至第三方认证接口完成认证工作。

接口说明:

接口调用鉴权

第三方采用计算checksum方式对调用方进行鉴权校验,参数包括两部分,header参数和body参数

Header参数,需要放在Http Request Header中

参数名 参数说明
checksum 请求参数根据checksum算法计算出来的值
time 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数(String)

Body参数,需要以字节流方式接收,内容为Json字符串

参数名 含义
uid 用户身份信息
token 认证用authToken

Body参数对应Json数据格式:

{"uid":"uid-from-user-server","token":"auth-token-from-user-server"}

计算checksum的java代码举例如下:

 public class QiyuAuthCheckSum {

    private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};

    public static String encode(String appSecret, String nonce, String time) {
        String content = appSecret + nonce + time;
        try {
            MessageDigest messageDigest = MessageDigest.getInstance("sha1");
            messageDigest.update(content.getBytes());
            return getFormattedText(messageDigest.digest());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private static String getFormattedText(byte[] bytes) {
        int len = bytes.length;
        StringBuilder buf = new StringBuilder(len * 2);
        for (int j = 0; j < len; j++) {
            buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
            buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
        }
        return buf.toString();
    }
}

encode函数参数来源说明:

参数名 含义
appSecret 登录第三方在七鱼平台账号的管理员端,在设置-基础设置-App接入页面可以查看到
nonce 将body参数对应的Json字符串参数进行md5加密后得到的值全部转小写后的值
time 取自header参数中的time参数值

接口响应:

{"code":200,"result":false}

响应字段:

字段 含义
code 响应码
result 认证结果

响应码值说明:

后续可按需扩展。

版本支持

支持用户认证的SDK版本如下:

平台 版本
Web-SDK >=3.5.0
iOS-SDK >=3.5.0
Android-SDK >=3.5.0

示例代码

Web

WEB-SDK提供如下两种方式设置及更新Token参数:

  1. ysf.config 设置 authToken 属性
  2. 调用 pollAuthTokensetAuthToken 设置 authToken
pollAuthToken(url, options)
接口描述

此接口使用http请求主动拉第三方接口更新token, 由于网络原因等异常情况会导致http请求, 一旦请求失败会执行重试机制,保证token的更新, 用户可以自定义重试次数(默认为4次)。

  1. 第三方自定义获取tokenapi的接口
  2. 更新防止 token 失效
请求说明
 GET http://domain/api/getAuthToken // 获取token的第三方的Api接口
 Content-Type : application/x-www-form-urlencoded;charset=utf-8
参数说明
字段 类型 必须 说明
interval Number 轮询时间间隔
retryTime Number 重试次数,默认为4
data Object 请求参数
method String GET
onsuccess Function 成功回调 code==200才进入此回调
onerror Function 失败回调
    var url = 'http://domain/api/getAuthToken' //  获取token的第三方的Api接口
    var options = {
        interval : 300000,  // 每隔多少毫秒去更新Token
        data : {},          // 请求参数
        retryTime : 4,      // 失败重试次数
        method : 'GET',     // 默认 GET 请求
        onsuccess : function(result){
            // 可选回调, 第三方业务逻辑
        },
        onerror : function(json){
            // 可选回调, 第三方业务逻辑
        }
    }

    ysf.pollAuthToken(url, options);
响应说明
 Content-Type : application/json;charset=utf-8
参数说明
字段 类型 说明
code Number 状态码
message String 返回消息说明
result Object {authToken : ''} authToken必填
setAuthToken(token)
接口说明

第三方主动调用此setAuthToken接口更新用户鉴权的 token

iOS

设置 authToken :

[[QYSDK sharedSDK] setAuthToken:@"auth-token-from-user-server"];

设置轻量 CRM :

/**
 *  完成回调
 */
typedef void(^QYCompletionWithResultBlock)(BOOL isSuccess);

/**
 *  设置个人信息,带authToken校验。用户帐号登录成功之后,调用此函数
 *
 *  @param userInfo 个人信息
 *  @param block authToken校验结果的回调
 */
- (void)setUserInfo:(QYUserInfo *)userInfo 
                authTokenVerificationResultBlock:(QYCompletionWithResultBlock)block;

Android

// 关联用户信息代码中增加以下字段:
YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId = "userId";
userInfo.authToken = "auth-token-from-user-server";
if (!Unicorn.setUserInfo(account, new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        ToastUtils.show("已切换为" + userInfo.userId, Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onFailed(int code) {
        if (code == 414) {
            ToastUtils.show("鉴权失败");
        } else {
            ToastUtils.show("设置用户资料失败,请重试");
        }
    }

    @Override
    public void onException(Throwable exception) {}
})) {
    ToastUtils.show("用户资料格式不对", Toast.LENGTH_SHORT).show();
}

注意事项