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

简介

概述

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

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

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

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

文档约定

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

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

客服工作台客服工作界面:都是指网易七鱼系统提供给客服使用的工作环境,即客服登录网易七鱼系统后使用的 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: https://xxx.qiyukf.com,http://xxx.qiyukf.com

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

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

接口认证方式

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

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

访客身份识别

七鱼通过用户唯一标识来识别访客身份,不同的接入渠道中所使用的用户唯一标识有所区别:

Web接入

Web将用户发起会话时上报的uid作为用户唯一标识,在接入七鱼的网页中,调用ysf.config()函数,将uid传给七鱼,示例如下:

ysf.config({
        uid:”123456”
    });

移动端SDK接入

Android SDK需在发起会话时上报uid作为用户唯一标识,上报方法:创建一个YSFUserInfo实例,将包含用户信息的 JSON 字符串填充到YSFUserInfo.data。调用Unicorn.setUserInfo()时将此YSFUserInfo实例作为参数传递给网易七鱼 SDK。示例如下:

YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId="uid";
Unicorn.setUserInfo(userInfo);

iOS SDK需在发起会话时上报uid作为用户唯一标识,上报方法:创建一个QYUserInfo实例,将包含用户信息的 JSON 字符串填充到QYUserInfo.data。调用setUserInfo时将此QYUserInfo实例作为参数传递给网易七鱼 SDK。示例如下:

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
[[QYSDK sharedSDK] setUserInfo:userInfo];

微信接入

使用授权方式完成的微信接入,七鱼会将访客微信OpenID作为用户唯一标示。此种方式接入,需要对接企业维护OpenID与企业原有用户体系的对应关系。 使用H5页面嵌入方式完成的微信接入,由于七鱼无法获取到OpenID,与Web接入类似的,需要通过ysf.config()函数,将访客uid传给七鱼。

电话接入

呼叫中心将以访客呼入电话号码作为用户唯一标识。

获取 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 /get_call_user_info 呼叫中心获取电话用户信息

网易七鱼系统在需要获取访客详细信息时,会调用该接口。该接口请求类型不同于token,前端会自动发送两次请求,第一次的请求类型是OPTION,第二次的请求类型是POST,且POST提交数据的方式为application/json

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

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

请求

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

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

备注:平台电商中的用户信息对接参数将增加shopid,获取对应商户下的用户信息。

响应

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

{
    "rlt": 0,
    "data": [
        {"index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "url"},
        {"index": 1, "key": "name", "label": "姓名", "value": "土豪", "edit": true, "map": "real_name", "href": "url"},
        {"index": 2, "key": "phone", "label": "手机", "value": "13800000000", "edit": true, "map": "mobile_phone", "href": "url"},
        {"index": 3, "key": "email", "label": "EMail", "value": "13800000000@163.com", "edit": true, "map": "email", "href": "url"},
        {"index": 4, "key": "vip", "label": "会员", "value": [{"id": 0,"name": "类型一"},{"id": 1,"name": "类型三", "check": true},{"id": 2,"name": "类型二"}], "select": true}
    ],
    "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 中出现的顺序排列。
href String 超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址。
edit Boolean 表示该项数据是否可编辑,true为可编辑,false为不可编辑。可编辑时该项数据的值将显示在一个输入框内,内容被编辑后将调用modify_cb接口提交更新。
map String 表明该项数据是否与网易七鱼系统中固定的数据项有映射关系。如真实姓名为real_name,手机号为mobile_phone,电子邮箱为email。如果一个数据项指定了正确的map值,则该数据也会同步显示在“当前会话”中右侧用户资料区的“用户资料”标签页下对应的项目中,以及“历史会话”中右侧会话详情区的“用户资料”标签页下对应的项目中。
save Boolean 是否将姓名、邮箱、手机号三个保留字段数据保存到网易七鱼系统中。true为保存,false或为空时不保存。将数据保存到网易七鱼系统有助于“历史会话”搜索和列表展示,不保存时则无法通过该项数据进行搜索。
zone Boolean 用于表明该项数据信息的展现位置。不设置表示仅显示在呼叫中心和在线会话“更多信息” 的标签下。true表示同时可显示在呼叫中心的“账户资料”和在线会话的“用户信息”的页面中。
select Boolean 用于标识该项数据是否为select下拉框。true表示该项数据为select下拉框的形式,且当select选项为true时,value字段应该为一个数组的形式。
check Boolean 配合select一起使用,用于标识该select下拉框选项是否被选中。true表示该数据项被选中,且check为true的选项仅有一个。

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

更新用户信息

POST /[modify_cb]

用户的唯一性标识和被修改的信息会被作为请求内容 POST 到该接口,与获取信息不一样的是,更新类接口POST提交数据的方式为application/x-www-form-urlencoded

接口地址由获取用户信息接口/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 在线会话获取用户订单信息

POST /get_call_order 呼叫中心获取用户订单信息

网易七鱼系统在调用获取访客详细信息接口/get_user_info时,会调用该接口。该接口企业在发送请求时,前端会自动发送两遍,第一遍的请求类型是OPTION,第二遍的请求类型是POST,提交数据方式采用application/json的方式。该接口可用于电商行业订单类信息,也可以用于金融行业交易类信息。

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

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

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

请求

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

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

备注::平台电商中的订单信息对接参数将增加shopid,获取对应商户下的订单信息。

响应

接口应该返回包含指定用户订单类数据列表的一段 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表示不是标题行。当一个区块是标题行时,它将会以订单标题的样式进行显示;而且点击该区块时,该订单会有展开/收起表现,被指定为is_title的项,它的data数据项的返回数组仅能有一个元素作为订单标题显示。

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

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。
value Mixed 该数据显示的值,类型不做限定,根据实际需要进行设定。
label String 该项数据显示的名称。
index Int 用于排序,显示数据时数据项按index值升序排列;不设定index的数据项将排在后面;index相同或未设定的数据项将按照其在 JSON 中出现的顺序排列。
href String 超链接地址。若指定该值,则该项数据将显示为超链接样式,点击后跳转到其值所指定的 URL 地址。
edit Boolean 表示该项数据是否可编辑,true为可编辑,false为不可编辑。可编辑时该项数据的值将显示在一个输入框内,内容被编辑后将调用modify_cb接口提交更新。
select Boolean 用于标识该项数据是否为select下拉框。true表示该项数据为select下拉框的形式,且当select选项为true时,value字段应该为一个数组的形式。
check Boolean 配合select一起使用,用于标识该select下拉框选项是否被选中。true表示该数据项被选中,且check为true的选项仅有一个。

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

示意图,敬请期待

更新订单信息

POST /[modify_cb]

订单用户的唯一标识和被修改的信息会被作为请求内容 POST 到该接口,与获取信息不一样的是,更新类接口POST提交数据的方式为application/x-www-form-urlencoded

接口地址由获取订单信息接口get_order返回的modify_cb的内容指定。

请求

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

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

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

字段
类型 必须 说明
key String 数据项的名称,用于区别不同的数据。key的值来源于获取订单信息/get_order接口返回的信息中对应数据项的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_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字段,提供用于显示的错误信息。

客户中心数据导入

调用说明

数据校验

七鱼服务器和您的服务器进行数据传递时,POST请求会带以下这些参数:

参数 参数说明
appKey 你的企业的appKey (仅在您的服务器向七鱼服务器发送数据时需要,七鱼服务器向您的服务器发送数据时无此参数)
time 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数
checksum SHA1(appSecret + md5 + time), 三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写)
eventType 七鱼服务器向开发者服务器推送事件时的事件类型。(开发者服务器向七鱼服务器发送请求时无此参数)

其中,checksum 用于校验数据的完整性,其计算规则中,AppSecret 可在七鱼管理页面「设置」->「消息接口」页面找到,md5 为整个请求 json 字符串的 md5 哈希值(小写形式),即 md5 = MD5(content).toLowwerCase(),如果是上传文件,则是整个文件内容的 md5,time 就是请求参数中的 time。处于安全性考虑,每个 checksum 的有效期为 5 分钟,请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。

计算 checksum 的 Java 示例代码如下:

 public class QiyuPushCheckSum {

    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();
    }
}

重要提示: 本文档中提供的所有接口均面向开发者服务器端调用,用于计算 checksum 的 AppSecret 开发者应妥善保管,可在应用的服务器端存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。

接口参数说明

使用该接口可以批量更新客户中心中的客户资料,支持批量新增、修改、删除客户资料。

服务器收到的POST请求如下:

POST https://qiyukf.com/openapi/crm/syncCrmInfo?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8

请求内容示例如下:

{
   "update":
   [{
      "name":"周明月",
      "phone":"13725698555",
      "email":"mingyue@163.com",
      "address":"河南省开封市祥符区范庄村",
      "firstContactTime":1483009843582,
      "lastContactTime":1483957441234,
      "车牌号":"豫BWD001"
   },{
      "name":"鲁城",
      "phone":"13725698666",
      "email":"lucheng@163.com",
      "address":"河南省开封市祥符区范庄村",
      "firstContactTime":1483009963521,
      "lastContactTime":1483957965821,
      "车牌号":"豫BWD002"
   }],
   "delete":
   [{
      "phone":"13725698001"
   }, {
      "phone":"13725698002"
   }]
}

请求参数说明如下:

参数 是否必须 参数说明
update 需要更新的客户信息
delete 需要删除的客户信息
phone 电话号码,做为客户资料的唯一标识
name 访客姓名,更新时必须传
email 访客邮箱
firstContactTime 首次联系时间,必须为毫秒数
lastContactTime 末次联系时间,必须为毫秒数
车牌号 作为自定义扩展字段

更新JSON参数中必须包含update或delete子元素其一。phone作为客户资料的唯一标识,如果系统中不存在phone对应的客户,则执行新增操作,否则执行更新操作。update中不允许存在两条phone一样的客户资料。在「客户中心记录字段」中配置了的,并且启用、显示的字段可以作为扩展字段,以「字段名称」作为属性名,如“车牌号”参数。如果扩展字段在「客户中心记录字段」中配置的字段类型是时间控件,则值必须为毫秒数,如firstContactTime,如果字段类型是数字,则值必须为数字。

响应参数中各个 key 意义与分配客服的响应参数相同,另外两个不同的key值意义如下:

参数 参数说明
code 错误码。200表示设置成功。
message 错误提示信息