# 网易七鱼企业信息对接开发指南
# 简介
# 概述
网易七鱼系统可以与企业 CRM 系统进行对接。
对接分轻量对接与接口对接两种方式。cho
- 轻量对接是指通过 Web / iOS / Android SDK 发起会话时，将访客的信息作为参数传递给网易七鱼系统。
- 接口对接是指企业提供一系列 HTTP/HTTPS 接口，由网易七鱼系统调用，获取访客的相关信息，并可以实现数据同步、访客身份验证等高级功能。
轻量对接的数据由企业产品客户端（或网站）将数据提交给网易七鱼系统，数据将展现在客服工作界面的当前会话和历史会话的“用户资料”标签下。接口对接的数据由企业接口提供，由网易七鱼系统客服端调用，数据将展现在客服工作界面的当前会话和历史会话的“更多信息”标签下。
轻量对接和接口对接的具体说明，请分别阅读轻量 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介绍 (opens new window)、JSON在线校验工具 (opens new window)。
# 轻量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, "value":"13800000000"},
{"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"},
{"index":7, "key": "tags", "label": "标签", "value": "企业,vip" }
])
});
注意：data字段的内容需使用JSON.stringify()进行序列化。为保持良好的兼容性，若要支持较低版本的浏览器（如IE8及更低版本）则需引入第三方JSON库，如 JSON3 (opens new window)。
# 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, \"value\":\"13800000000\"},"
"{\"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\"},"
"{\"index\":7, \"key\":\"tags\", \"label\": \"标签\", \"value\": \"企业,vip\"}"]";
[[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, \"value\":\"13800000000\"},
{\"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\"},
{\"index\":7, \"key\": \"tags\", \"label\": \"标签\", \"value\": \"企业,vip\" }]";
Unicorn.setUserInfo(userInfo);
# 小程序 session-from 接入
在小程序会话接入时，通过session-from属性将包含用户信息的JSON数据放在ysf.config字段中传递给网易七鱼系统。示例如下：
<button type="primary" size="40"
session-from="nickName={{userInfo.nickName}}|avatarUrl={{userInfo.avatarUrl}}|foreignid={{userInfo.foreignid}}|referrerTitle={{ysf.title}}|ysf.config= {{ysf.config}}"
open-type="contact"
>点我给客服发送消息</button>
数据格式如下：
ysf:{
title: '详情页',
config: JSON.stringify({
"level":1, // vip等级
"data": JSON.stringify([
{ "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" }
{ "index": 7, "key": "tags", "label": "标签", "value": "企业,vip" }
])
})
}
# 参数说明
网易七鱼系统轻量对接中的参数，不论是 Web SDK、iOS SDK、还是 Android SDK，都由一个用户唯一性标识uid和一个表示用户信息的 JSON 数组data组成。
在 Web SDK 中uid和data都直接出现在 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.userId；data分别对应 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_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不隐藏。 |
isCustomField | Boolean | 否 | 是否属于自定义字段。如果是，则尝试匹配自定义字段名称并更新值，目前只支持 文本、数字、时间、单选、多选(用 ### 分割选中值，其中###前后都有空格)。 |
注意： real_name、mobile_phone、email三个保留字段的特别说明：
- 若使用保留字段，数据将对应显示在“姓名”、“手机”、“邮箱”的位置上，顺序、名称不能指定；
- 若使用保留字段，“姓名”、“手机”、“邮箱”对应的数据将不可编辑，以传递的数据为准；在不使用保留字段的情况下，这三项内容以客服填写的为准，并且可以修改；
- 其中
mobile_phone、email两项可以通过hidden字段隐藏，real_name不可隐藏； - 如果既想通过轻量对接提供“姓名”、“手机”、“邮箱”这三项数据，又希望客服可以修改、维护这些信息，可以避开保留关键字，用不同的
key来提供数据；这在访客改变了联系方式，但没有及时更新用户信息的情况下非常有用。
注意： 提交的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在提交时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。
注意： tags字段说明：
- key值为'tags'时，该行数据对应七鱼系统内的用户标签数据
- 更新方式为覆盖，value内为标签名，以逗号分隔（注意不带空格，英文逗号），传入时会与七鱼系统内标签信息进行比对，如果标签名一致，会将该用户标签属性更改为传入的标签属性。value如果为空值，则不做更改（不会将用户标签属性清空）。
- 如果轻量crm和crm接口对接都有key为'tags'的数据，且二者值不同，将用接口数据覆盖轻量数据
# 企业 CRM 接口对接
# 概要
企业CRM接口由企业开发者开发实现，并填写在七鱼后台的“设置--信息对接-CRM信息对接”中；当用户接入时，七鱼会调用相应接口，使用轻量对接中传递的uid；开发者在七鱼后台设置的appid以及获取token接口中拿到的token，去请求获取用户信息等接口，并将开发者的正确返回展示在当前客服聊天页面右侧的“更多信息”标签下（在“历史咨询”中也适用）。
企业实现这些接口，可以为网易七鱼系统提供用户信息、订单信息等 CRM 数据，以便客服在工作时方便地获得丰富的信息，更好的提供服务。
企业接口为一系列 HTTP （或 HTTPS）接口，由网易七鱼系统发起调用。网易七鱼系统与企业 CRM 系统通过这些接口进行数据交换，数据通常以 JSON 格式展现。即：
- 网易七鱼系统调用企业接口时，通常是向企业接口 POST 一段描述请求内容的 JSON，企业发送该请求会自动发送两遍，第一个请求是OPTION类型，第二个请求是POST类型；（两个请求都需要支持跨域访问）
- 企业接口返回数据给七鱼系统时，也返回一段包含所请求的数据的 JSON。
数据格式请仔细阅读每个接口的说明。
为保证数据的安全、并考虑一定的扩展性，企业需提前给网易七鱼系统分配appid、appsecret用于接口调用时的认证。认证方式见下。
本文档中的接口地址都为相对路径。接口完整的 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应该替换为企业在网易七鱼系统上申请的二级域名（或者可以直接设置允许全部 Access-Control-Allow-Origin: *）。
更多信息请参考 W3C Recommendation: Cross-Origin Resource Sharing (opens new window)。
# 接口认证方式
接口认证方式有两种可选：
- 若企业提供获取token并且通过该接口可以获取到token时，则后续所有请求通过
appid、token来确认请求的合法性（如本文档所示）； - 若企业不提供获取 token 并且通过该接口获取到的响应为空时，则所有请求都直接用
appsecret当做token来使用。
认证参数传递方式也有两种可选：
- 放在request body的JSON中：参数的键名为
"appid"、"token"（如本文档所示）； - 放在request的头域(Header)中：参数的域名为
"X-App-Id"、"X-Token"。
# 访客身份识别
七鱼通过用户唯一标识来识别访客身份，不同的接入渠道中所使用的用户唯一标识有所区别：
# 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",
"staffphone": "057189850000"
}
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
appid | String | 是 | 企业分配给网易七鱼系统的 appid。 |
token | String | 是 | 当前有效的 token。 |
userid | String | 是 | 用户的唯一性标识。 |
staffphone | String | 否 | 企业和用户联系时使用的中继号码。 |
注意：userid来源于用户发起会话时，调用各端 SDK 的初始化代码时传递给网易七鱼系统的参数中。
**备注：**平台电商中的用户信息对接参数将增加shopid,获取对应商户下的用户信息。
# 响应
接口应该返回一段包含用户数据的 JSON。
{
"rlt": 0,
"uid": "zhangsan",
"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},
{"index": 5, "key": "tags", "label": "标签", "value": "企业,vip"}
],
"modify_cb": "url"
}
字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
rlt | Int / String | 是 | 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。 |
uid | String | 否 | get_call_user_info接口返回该字段，用于将同一用户手机号和uid关联，打通呼叫和在线历史咨询记录 |
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字段应该为一个数组的形式（可以在value中指定初始化check为true的默认选中现，如果没指定则默认选中第一项）。 |
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": 2,
"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, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险" , "href": "url"},
{"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"},
{"index": 4, "key": "revenue_amount", "label": "累计收益", "value": "2.00元" }
]
}
]
},
{
"index": 1,
"blocks": [
{
"index": 0,
"is_title": true,
"data": [
{ "index": 0, "key": "orderid", "label": "订单号", "value": "00002", "href": "url"}
]
},
{
"index": 1,
"data": [
{"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
{"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"},
{"index": 2, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险" , "href": "url"},
{"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"},
{"index": 4, "key": "revenue_amount", "label": "累计收益", "value": "2.00元" }
]
}
]
}
]
}
字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
rlt | Int / String | 是 | 表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见Appendix I节。 |
count | Int | 是 | 表示该用户订单类数据的条目总数，而非此次请求返回的订单数量。用于控制分页。 |
orders | Array | 是 | 用一个数组表示用户订单列表的数据。 |
订单列表有多层数据嵌套：
orders的每一个元素表示一个订单；- 每个订单的信息可以按照内容分类，分割成多个区块进行显示，订单的
blocks数组里保存了这些区块； - 每个区块中用一个
data数组保存具体的数据，与用户详细信息数据类似，数组中每个元素代表一个数据项，数据项以<key, value>对的形式为基础，增加了额外的字段以控制显示样式。
以下为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数据项的返回数组仅能有一个元素作为订单标题显示。每个blocks中都需要指定一个区块作为标题。 |
以下为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字段应该为一个数组的形式value字段应该为一个数组的形式（可以在value中指定初始化check为true的默认选中现，如果没指定则默认选中第一项）。 |
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 | 是 | 该项数据修改失败的错误提示。 |
# 自定义接口参数
网易七鱼系统提供自定义配置获取用户信息和获取订单信息接口参数的功能。针对会话的场景，网易七鱼提供了在访客接入时采用扩展crm接入的方式自定义配置接口crm请求的参数。
自定义参数的扩展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"},
{"type": "crm_param", "key": "startTime", "value": "2017-05-20", "area": "user"},
{"type": "crm_param", "key": "endTime", "value": "2017-05-21", "area": "order"},
{"type": "crm_param", "key": "creatTime", "value": "2017-05-20"}
])
});
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
type | String | 是 | 向七鱼声明配置类型为自定义参数类型 |
key | String | 是 | 规定请求接口时，自定义参数的参数名字 |
value | String | 是 | 规定请求接口时，自定义参数的参数值 |
area | String | 否 | 规定自定义参数请求接口的影响范围 |
其中area值为user时，表示只应用在获取用户信息接口，值为order时，表示只应用在获取订单信息接口，不设置area会分别应用在获取用户信息和订单的两个接口。
# 对接方式对比与建议
轻量对接与接口对接的比较。场景、开发难度、数据隔离。
建议不同的企业、团队，用不同的对接方式。
轻量对接方式与接口对接方式，都是为了给客服在服务过程中提供丰富的访客信息，从而提高服务质量与工作效率。然而两种对接方式在使用场景与实现方式方面各有不同，以下对两种对接方式进行对比。
对比角度 | 轻量对接 | 接口对接 |
|---|---|---|
| 数据来源 | 发起会话时，客户端通过 SDK 提交。 | 企业提供的 HTTP 接口。 |
| 调用方式 | 客户端通过 SDK 将数据提交给网易七鱼系统服务器，客服工作台向网易七鱼服务器发起请求。 | 客服工作台直接向企业提供的 HTTP 接口发起请求。 |
| 数据存储 | 访客数据加密后保存在网易七鱼系统。 | 客服工作台前端直接发起请求，数据不经网易七鱼服务器，完全隔离。 |
| 功能 | 展现自定义访客信息：√ 展现订单类数据：× 数据与企业 CRM 同步：× 访客信息验证：× | 展现自定义访客信息：√ 展现订单类数据：√ 数据与企业 CRM 同步：√ 访客信息验证：√ |
| 展现位置 | 当前会话和历史会话的“用户资料”标签下 。 | 当前会话和历史会话的“更多信息”标签下。 |
| 开发难度 | 低。 只要客户端有访客的相关数据，就可以按约定拼出 JSON 提交。 | 中。 需要开发一套 HTTP 接口，与企业 CRM 数据库对接。若已有类似接口，则非常容易进行对接。 |
| 开发成本 | 低。 可快速实现。 无特别要求。 | 中。 需要一定的人力进行开发。 需支持跨域。 |
| 适用场景 | 产品规模较小； 产品发展初期； 团队规模较小； 技术人力紧张； 企业 CRM 尚不完善； 访客数据要求一般； 不需要订单、交易类信息。 | 产品规模中大； 产品发展成熟期； 团队规模中大； 技术人力有一定支持； 企业 CRM 较完善； 访客数据要求高； 需要订单、交易类信息。 |
# Appendix I 错误码
所有对接接口rlt错误码保留值定义如下：
0: 接口返回正确；1: 用appid和appsecret作为认证方式时，表示认证不通过；2: 用appid和token作为认证方式时，表示 token 过期；
其他情况，可根据企业业务逻辑自行设定错误码，仅供显示用。
有关认证方式的说明，请参考接口认证方式章节。
所有错误码，包括保留的错误码，均可使用整形或字符串。即：
{
"rlt": 0
}
{
"rlt": "0"
}
两种表示方法是等价的。
当接口返回的rlt字段值不为0时，可以在返回的内容中设置一个msg字段，提供用于显示的错误信息。
# 客户中心数据导入
该接口是针对呼叫中心的用户数据设计的，所以phone参数为必须且真实有效的数据。调用该接口需要使用appkey和appsecret，该参数在“设置-信息对接-开发者ID”中获取。首次进入信息对接页面时，开发者ID中只有appkey，appsecret项只有一个“重置”按钮，点击之后会第一次生产appsecret，之后再次点击就是刷新appsecret。 *开发者ID信息一般用于消息接口，只有专业版及以上才有此模块。
# 调用说明
- 本接口只支持POST请求；
- 本接口请求Content-Type类型为：application/json;charset=utf-8；
- 本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
七鱼服务器和您的服务器进行数据传递时，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":"河南省开封市祥符区范庄村",
"leader":-1,
"firstContactTime":1483009843582,
"lastContactTime":1483957441234,
"plateNumber":"豫BWD001"
},{
"name":"鲁城",
"phone":"13725698666",
"email":"lucheng@163.com",
"address":"河南省开封市祥符区范庄村",
"leader":124548,
"firstContactTime":1483009963521,
"lastContactTime":1483957965821,
"plateNumber":"豫BWD002"
}],
"delete":
[{
"phone":"13725698001"
}, {
"phone":"13725698002"
}]
}
请求参数说明如下：
| 参数 | 是否必须 | 参数说明 |
|---|---|---|
| update | 否 | 需要更新的客户信息 |
| delete | 否 | 需要删除的客户信息 |
| phone | 是 | 电话号码，做为客户资料的唯一标识 |
| name | 是 | 访客姓名，更新时必须传 |
| 否 | 访客邮箱 | |
| address | 否 | 地址 |
| leader | 否 | 负责人客服ID，可在设置->高级设置->访客分配->ID查询处查询。如果要清除负责人，设置值为-1 |
| firstContactTime | 否 | 首次联系时间，必须为毫秒数 |
| lastContactTime | 否 | 末次联系时间，必须为毫秒数 |
| plateNumber | 否 | 作为自定义扩展字段 |
更新JSON参数中必须包含update或delete子元素其一。phone作为客户资料的唯一标识，如果系统中不存在phone对应的客户，则执行新增操作，否则执行更新操作。update中不允许存在两条phone一样的客户资料。在「客户中心记录字段」中配置了的，并且启用、显示的字段可以作为扩展字段，以「字段名称」作为属性名，如plateNumber参数。若未提前配置并启用，在导入数据后将查看不到对应的扩展字段（因为在调用接口导入过程中，服务端会直接忽略这些数据）。如果扩展字段在「客户中心记录字段」中配置的字段类型是时间控件，则值必须为毫秒数，如firstContactTime，如果字段类型是数字，则值必须为数字。
响应参数中各个 key 意义与分配客服的响应参数相同，另外两个不同的key值意义如下：
| 参数 | 参数说明 |
|---|---|
| code | 错误码。200表示设置成功。 |
| message | 错误提示信息 |
# 七鱼用户认证机制
# 概要
# 术语
- 第三方：接入七鱼的企业
uid：第三方的用户唯一标识
# 简介
第三方接入七鱼后，可以上报uid，用以访问或关联用户在第三方的真实业务数据。本文描述了七鱼对uid进行身份认证的方案。适用于对uid真实性要求较高的场景。
# 方案
# 认证过程
- 第三方提供一个生成随机授权码
authToken的授权接口，authToken生成后需要暂存在第三方服务器端，供之后的uid校验使用； - 申请客服或上报CRM信息请求时，先调用上面接口，获取随机授权码
authToken，并将其传递给七鱼； - 七鱼前端将获取到的
authToken和uid作为参数传递到七鱼服务器端； - 七鱼服务器收到请求后，携带
authToken和uid，调用第三方认证接口进行校验； - 第三方将收到的
authToken与本地暂存的authToken进行比较，看是否一致，并返回校验结果； - 如果
authToken和uid校验失败，七鱼服务器会忽略请求，并返回失败信息到前端页面。
# 实施流程
- 第三方知会七鱼需开启用户认证，并协调约定开启时间；
- 第三方在约定的开启之前准备好
认证接口，将线上接口地址提交给七鱼，并与七鱼做好联调工作； - 第三方使用支持的SDK，并按下文中代码示例完成
authToken的设置工作。
# 授权接口
生成随机授权码authToken的接口。该接口可以由第三方自己调用，也可以将其url地址提供给七鱼，由七鱼代理获取。
如果该接口由第三方自己调用，需要第三方自己保证生成的authToken在使用时不会过期，如定期将新生成的authToken通过七鱼SDK接口函数传递给七鱼。七鱼不关心该接口的定义规则。
如果该接口由七鱼调用，则第三方不需要关心authToken的过期问题，但接口必须遵循以下定义规范：
# 调用说明：
- 接口由第三方提供
- 调用方式为HTTP GET请求；
- 接口认证方式与第三方平台Session认证一致
- 接口返回类型为JSON，同时进行UTF-8编码。
响应实例：
{"code":200,"token":false}
响应字段：
| 字段 | 含义 |
|---|---|
| code | 响应码，200表示生成authToken成功 |
| token | 新生成的authToken值 |
# 认证接口
七鱼服务端收到相关请求后，会携带认证信息至第三方认证接口完成认证工作。
# 接口说明：
- 接口由第三方提供
- 调用方式为HTTP POST请求；
- 请求Content-Type类型为：application/json;charset=utf-8；
- 接口返回类型为JSON，同时进行UTF-8编码。
# 接口调用鉴权
第三方采用计算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 | 认证结果 |
响应码值说明：
- 200，表示接口校验成功，result返回true
- 300，表示
checksum计算错误，result返回false - 400，表示token值校验失败，result返回false
后续可按需扩展。
# 版本支持
支持用户认证的SDK版本如下：
| 平台 | 版本 |
|---|---|
| Web-SDK | >=3.5.0 |
| iOS-SDK | >=3.5.0 |
| Android-SDK | >=3.5.0 |
# 示例代码
# Web
WEB-SDK提供如下两种方式设置及更新Token参数:
ysf('config')设置authToken属性- 调用
pollAuthToken或setAuthToken设置authToken值
# pollAuthToken(url, options)
# 接口描述
此接口使用http请求主动拉第三方接口更新token, 由于网络原因等异常情况会导致http请求, 一旦请求失败会执行重试机制，保证token的更新, 用户可以自定义重试次数(默认为4次)。
- 第三方自定义获取
token的api的接口 - 更新防止
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();
}
# 注意事项
authToken需在申请客服动作发生时保证可用性；- 认证过程中
authToken的产生比较关键，为保证安全性，需要在访客成功登录第三方平台后才能请求授权接口获取authToken。
# 一触即达对接
本文档为一触即达接入文档，企业根据不同业务模块，使用一触即达功能需要实现对应模块的http查询接口。 根据企业是否允许匿名访客查询，调用查询接口方式分为匿名访客查询和有名访客查询，匿名访客是指企业未做过CRM信息对接的访客，匿名访客查询是允许所有连接到机器人客服的访客使用该查询接口，有名访客查询是只允许做过CRM信息对接的访客才可使用该查询。但查询某些信息时（如查订单等需要用户唯一标识的查询）必须要企业提供访客唯一标识，即企业需通过CRM信息对接提供给七鱼。
# 对接方式
说明：所有接口均需符合七鱼对企业接口的请求格式规范和返回格式规范，其规范见下文。 目前七鱼调用第三方接口时会加上的鉴权方式有两种，一是token校验（复用CRM信息对接里获取token的接口，若能获取到token则使用该token，获取不到token则不使用，此种需企业提供appId,appSecret和获取token的接口），另一种是checkSum校验，需企业提供appId和appSecret,生成checkSum方式见下文。企业可依据不同模块情况采用任意校验方式，或不使用身份校验。
- 企业接口请求说明
- 获取token接口的请求方式同CRM对接文档里相同；
- 一触即达的所有接口请求均为POST请求；
- 一触即达的所有接口请求的Content-Type类型均为：application/x-www-form-urlencoded;charset=utf-8。 例：
POST https://qiyeserver/... HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
- 企业接口返回说明
返回字段定义：
| 参数 | 是否必填 | 参数说明 |
|---|---|---|
| code | 是 | 请求的返回码 |
| desc | 否 | 描述信息 |
| result | 是 | 接口调用结果 |
- 所有一触即达企业接口的返回类型为JSON，同时进行UTF-8编码；
- 接口的返回值在result字段里，可以是任何对象，只有code=200时才认为调用成功，并使用result字段里的内容做后续操作。 例：
{
"code": 200,
"desc": "success",
"result": {
"id": "123456",
"name": "hello world",
"address": "浙江省杭州市滨江区长河街道网商路599号网易大厦"
}
}
- 接口调用流程
- 若接口不需请求校验并对所有人开放，则接口只需符合上文所列的请求和返回规范即可。
- 分配appId和appSecret，企业需在页面：接入设置->信息对接->CRM信息对接处填写给七鱼分配的appId和appSecret用于获取token和生成checkSum校验；
- 若企业设置了获取token接口，并且七鱼成功获取到token后，会在七鱼调用企业一触即达接口时将token作为参数带上；
- 七鱼在调用企业接口时，将appSecret，time，nonce三个参数使用sha1哈希算法生成checkSum校验和（同消息接口checksum校验和示例代码），其中time为精确到秒的时间戳，nonce为一串随机生成的字符串,参数放在Http Request Header中传输；
- POST请求调用第三方接口，七鱼会带上的请求参数有：userId（String字符串类型），plgCode（String字符串类型），params（Map键值对类型，包含请求所需参数，需要企业在一触即达查询节点里进行设置），请求参数放在请求体里。
- 参数说明
| 参数 | 是否必填 | 参数说明 |
|---|---|---|
| appId | 是 | 企业分配给七鱼的appId |
| nonce | 是 | 随机字符串（最大长度128个字符） |
| time | 是 | 当前UTC时间戳，精确到秒数 |
| checkSum | 是 | SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time顺序拼接成的字符串计算SHA1哈希值，并转化成16进制的小写字符串作为checkSum |
| userId | 是 | 开发者的应用里的用户ID，通过CRM接入同步给七鱼 |
| plgCode | 是 | 七鱼要调用的对应模块名称 |
| params | 是 | 调用第三方接口的参数列表，企业在一触即达的查询节点里进行配置 |
| token | 否 | 获取到的企业token |
# 对接示例
| 模板id | 说明 | SDK支持版本 |
|---|---|---|
| 01 | 文本 | 不限 |
| 02 | 文本+按钮列表 | 不限 |
| drawer_list | 抽屉列表 | >=5.1.0 |
| bubble_list | 气泡列表 | >=5.1.0 |
| bubble_node_list | 气泡节点列表 | >=5.1.0 |
| horizontal_sliding_list | 横滑卡片 | >=5.1.0 |
注：其他端不受版本限制
# 示例 1：文本
在一触即达的流程中，根据企业在节点中设置的提取变量，结合企业接口地址，获取文本消息并填充到模板中，返回示例为：
{
"code": 200,
"desc": "success",
"result": {
"data": {
"item_list": [
{
"item_type": 0,
"label": "七鱼客服bot对接"
},
{
"item_type": 1,
"label": "<a href="http://qiyukf.netease.com/">七鱼客服</a>"
}
]
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| item_type | Int | 是 | 文本类型，0-普通文本，1-富文本 |
| label | String | 是 | 文本内容 |
- xml模板填充样式
<template id="01">
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach($item in $!{data.item_list})
<LinearLayout>
#if($!{item.item_type} == 0)
<text name="label">$!{item.label}</text>
#else
<richText name="label">$!{item.label}</richText>
#end
</LinearLayout>
#end
#end
</template>
# 示例 2：文本+按钮列表
本模板为文本模板升级版，支持文本+按钮列表的样式。在一触即达的流程中，根据企业在节点中设置的提取变量，结合企业接口地址，获取文本消息并填充到模板中，返回示例为：
{
"code": 200,
"desc": "success",
"result": {
"data": {
"introducer": "引导语",
"item_list": [
{
"item_type": "0",
"label": "按钮1",
"params": "orderNo=0"
},
{
"item_type": "1",
"label": "按钮2",
"target": "http://qiyukf.netease.com",
"params": "orderNo=0"
}
]
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| introducer | String | 否 | 引导语文案 |
| item_list | Array | 是 | 按钮列表 |
- 按钮字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| item_type | Int | 是 | 按钮类型，0-跳转至下一个节点，1-跳转至外部链接 |
| label | String | 是 | 按钮文案 |
| params | String | 否 | 点击item跳转时携带的参数 |
| target | String | 否 | 跳转至下一个节点时可不传target，跳转至外部链接时需配置链接地址 |
- xml模板填充样式
<template id="02">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
</LinearLayout>
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach(${item} in $!{data.item_list})
#if($!{item.item_type} == 0)
<LinearLayout>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<text name="label">$!{item.label}</text>
</link>
</LinearLayout>
#else
<LinearLayout>
<link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
<text name="label">$!{item.label}</text>
</link>
</LinearLayout>
#end
#end
#end
</template>
# 示例 3：抽屉列表
抽屉列表可以用于展示订单列表或商品列表，支持展示图文内容，也支持仅展示文字内容，样式如图：
如果需要返回抽屉列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参tabId,currentPage（代表当前要请求第几页），pageSize（代表每页的大小是多少）。拉取抽屉列表时，七鱼调用企业服务器，例如：tabId=1,currentPage=1,pageSize=5，代表拉取第1个分组的第1页共5条数据（注意：若params包含的参数为空，默认拉取第1个分组的第1页共5条数据，即相当于tabId=1,currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。tabId和currentPage可以根据访客的点选动态赋值。在一触即达查询节点中的配置如下：
result返回值为企业订单列表的JSON数组，返回示例：
{
"code": 200,
"desc": "success",
"result": {
"data": {
"tab_id": 1,
"current_page": 1,
"page_size": 5,
"introducer": "请选择您想咨询的订单",
"banner": "选择咨询的订单",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"name": "分组1",
"item_list": [
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "考拉海购"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "网易严选"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
},
"tab2":{
"name": "分组2",
"item_list": []
},
"tab3":{
"name": "分组3",
"item_list": []
},
"tab4":{
"name": "分组4",
"item_list": []
}
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| tab_id | Int | 是 | 当前列表分组id，从params中获取，若params为空，默认为1 |
| current_page | Int | 是 | 当前页，从params中获取，若params为空，默认为1 |
| page_size | Int | 是 | 每页数据条数，从params中获取，若params为空，默认为5，最多不超过10条 |
| introducer | String | 是 | 引导语，不可为空值 |
| banner | String | 否 | 提示语 |
| empty_list_hint | String | 是 | 无数据返回提示文案，不可为空值 |
| tab1 | Object | 是 | 列表分组1，对应分组id为1 |
| tab2 | Object | 否 | 列表分组2，对应分组id为2 |
| tab3 | Object | 否 | 列表分组3，对应分组id为3 |
| tab4 | Object | 否 | 列表分组4，对应分组id为4 |
列表分组tab格式说明：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| name | String | 否 | 列表分组名称，如果不传则不展示该行内容 |
| item_list | Array | 是 | 列表分组中item分组数据和item详细数据 |
item分组数据(item_type=1)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为1 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题，可以为空 |
item详细数据(item_type=0)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为0 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题 |
| sub_title | String | 否 | 副标题 |
| attr_1 | String | 否 | 属性1 |
| attr_2 | String | 否 | 属性2 |
| attr_3 | String | 否 | 属性3 |
| params | String | 否 | 点击item跳转时携带的参数 |
| target | String | 否 | 点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空 |
注意事项：
<1> 为了降低企业对接难度和简化分页处理，item分组与item采用混排平铺的方式实现分组效果，item分组被当做一个特殊的item，两者的区别是item_type不同
<2> 抽屉列表要求至少包含一个列表分组，即tab1。当包含多个分组时，每次返回结果只需包含当前请求分组的item_list字段，但是需要填充其他分组的name字段。例如存在3个列表分组的情况下，在请求分组1的数据时，除了要填充tab1.name，tab1.item_list外，还需要填充tab2.name，tab3.name。
- xml模板填充样式
<template id="drawer_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="tab_id">$!{data.tab_id}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<group>
<tab>
<text name="tab_name">$!{data.tab1.name}</text>
</tab>
#if(1 == ${data.tab_id} && ${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(1 == ${data.tab_id})
#set($page_1 = ${data.current_page} + 1)
#else
#set($page_1 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=1¤tPage=$!{page_1}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab2.name}</text>
</tab>
#if(2 == ${data.tab_id} && ${data.tab2.item_list} && ${data.tab2.item_list.size()} > 0)
#foreach(${item} in $!{data.tab2.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_2}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(2 == ${data.tab_id})
#set($page_2 = ${data.current_page} + 1)
#else
#set($page_2 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=2¤tPage=$!{page_2}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab3.name}</text>
</tab>
#if(3 == ${data.tab_id} && ${data.tab3.item_list} && ${data.tab3.item_list.size()} > 0)
#foreach(${item} in $!{data.tab3.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="display" style="button" >
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(3 == ${data.tab_id})
#set($page_3 = ${data.current_page} + 1)
#else
#set($page_3 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=3¤tPage=$!{page_3}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab4.name}</text>
</tab>
#if(4 == ${data.tab_id} && ${data.tab4.item_list} && ${data.tab4.item_list.size()} > 0)
#foreach(${item} in $!{data.tab4.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(4 == ${data.tab_id})
#set($page_4 = ${data.current_page} + 1)
#else
#set($page_4 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=4¤tPage=$!{page_4}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
</template>
# 示例 4：气泡列表
气泡列表可以用于展示订单列表或商品列表，支持展示图文内容，也支持仅展示文字内容，样式如图：
如果需要返回气泡列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参currentPage,pageSize。拉取列表时，七鱼调用企业服务器，例如：currentPage=1,pageSize=5，代表拉取第1页共5条数据（注意：若params包含的参数为空，默认拉取的第1页共5条数据，即相当于currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。
result返回值为企业订单列表的JSON数组，返回示例：
{
"code": 200,
"desc": "success",
"result": {
"data": {
"current_page": 1,
"page_size": 5,
"introducer": "请选择您想咨询的订单",
"banner": "选择咨询的订单",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"item_list": [
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "item分组"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "item分组"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
}
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| current_page | Int | 是 | 当前页，从params中获取，若params为空，默认为1 |
| page_size | Int | 是 | 每页数据条数，从params中获取，若params为空，默认为5，最多不超过10条 |
| introducer | String | 是 | 引导语，不可为空值 |
| banner | String | 否 | 提示语 |
| empty_list_hint | String | 是 | 无数据返回提示文案，不可为空值 |
| tab1 | Object | 是 | 列表分组，气泡列表仅支持一个列表分组 |
列表分组格式说明：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| item_list | Array | 是 | 列表分组中item分组数据和item详细数据 |
item分组数据(item_type=1)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为1 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题，可以为空 |
item详细数据(item_type=0)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为0 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题 |
| sub_title | String | 否 | 副标题 |
| attr_1 | String | 否 | 属性1 |
| attr_2 | String | 否 | 属性2 |
| attr_3 | String | 否 | 属性3 |
| params | String | 否 | 点击item跳转时携带的参数 |
| target | String | 否 | 点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空 |
- xml模板填充样式
<template id="bubble_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<group>
#if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#set($page = ${data.current_page} + 1)
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
</template>
# 示例 5：横滑卡片列表
横滑卡片列表可以用于展示商品列表，支持展示图文内容，样式如下：
如果需要返回横滑卡片列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参currentPage,pageSize。拉取列表时，七鱼调用企业服务器，例如：currentPage=1,pageSize=5，代表拉取第1页共5条数据（注意：若params包含的参数为空，默认拉取的第1页共5条数据，即相当于currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。
result返回值为企业订单列表的JSON数组，返回示例：
{
"code": 200,
"desc": "success",
"result": {
"data": {
"current_page": 1,
"page_size": 5,
"introducer": "引导语aaa",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"item_list": [
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/TB2Zo._a5GO.eBjSZFjXXcU9FXa_!!2228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
}
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| current_page | Int | 是 | 当前页，从params中获取，若params为空，默认为1 |
| page_size | Int | 是 | 每页数据条数，从params中获取，若params为空，默认为5，最多不超过5条 |
| introducer | String | 是 | 引导语，不可为空值 |
| empty_list_hint | String | 是 | 无数据返回提示文案，不可为空值 |
| tab1 | Object | 是 | 列表分组，横滑卡片列表仅支持一个列表分组 |
列表分组格式说明：
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| item_list | Array | 是 | 列表分组中的item详细数据 |
item分组数据(item_type=1)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为1 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题，可以为空 |
item详细数据(item_type=0)格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| item_type | String | 是 | 值固定为0 |
| img | String | 否 | 缩略图地址 |
| title | String | 否 | 标题 |
| sub_title | String | 否 | 副标题 |
| attr_1 | String | 否 | 属性1 |
| attr_2 | String | 否 | 属性2 |
| attr_3 | String | 否 | 属性3 |
| params | String | 否 | 点击item跳转时携带的参数 |
| target | String | 否 | 点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空 |
注意事项：
<1> 横滑卡片的数据填充企业可以按两种模式处理：一种是传统的分页模式，此时currentPage代表页码；一种是随机模式，此时currentPage代表轮次，可以随机返回item。企业可以根据不同场景选择合适的模式。
- xml模板填充样式
<template id="horizontal_sliding_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
</LinearLayout>
#if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#set($page = ${data.current_page} + 1)
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
<text name="label">换一批</text>
</link>
</action>
</template>
# 示例 6：气泡节点列表
气泡节点列表可以实现类似时间轴列表的效果，可以用于展示物流信息，企业也可以根据自己的需求灵活定制，样式如下：
拉取气泡节点列表时，七鱼调用企业服务器，目前不用在一触即达查询节点的接口配置中设置固定入参。result返回值为订单列表的JSON数组，返回示例为：
{
"code": 200,
"desc": "success",
"result": {
"data":
{
"introducer": "引导语",
"empty_list_hint": "无数据返回提示文案",
"banner": "标题",
"item_list": [
{
"title": "业务员二片区岸上蓝山正在第1次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "1"
},
{
"title": "业务员二片区岸上蓝山正在第2次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第3次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第4次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第5次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第6次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第7次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
}
]
}
}
}
- 字段说明
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
| introducer | String | 是 | 引导语，不可为空值 |
| banner | String | 否 | 标题 |
| empty_list_hint | String | 是 | 无数据返回提示文案，不可为空值 |
| item_list | Array | 是 | 列表 |
item数据格式说明:
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| title | String | 否 | 标题 |
| desc | String | 否 | 描述 |
| is_current | String | 是 | 是否停留在当前节点：1-是 0-否 |
- xml模板填充样式
<template id="bubble_node_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<LinearLayout>
<text name="label">$!{data.title}</text>
</LinearLayout>
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach($item in $!{data.item_list})
<LinearLayout>
<text name="p_title">$!{item.title}</text>
<text name="p_desc">$!{item.desc}</text>
<text name="p_is_current">$!{item.is_current}</text>
</LinearLayout>
#end
</LinearLayout>
#end
</template>
# Velocity语法赋值
如果企业需要定制一触即达输出的样式，企业需要与七鱼预先约定字段，并在一触即达中配置xml填充信息。配置xml时可参考以上xml模版填充样式。xml模版同时支持Velocity语法赋值，内容如下：
- 赋值
$!{参数名称}
- 遍历
#foreach ($item in $list)
#end
- 注：当接口返回结果的result结果为数组时，$list 可以直接是用 $result 赋值遍历。
#foreach ($item in $result)
#end
- 条件
#if($(orderDto))
订单对象有值
#else
订单对象为空
#end
#if(!$(orderDto))
订单对象为空
#else
订单对象有值
#end
- 变量约定
| 参数具体指代 | 约定在xml中的velocity的变量名称 | 样例 |
|---|---|---|
| 跳转至节点本身 | xml_nfid_block_self | target="${xml_nfid_block_self}" |
| 跳转至其他节点 | 前缀：xml_nfid_block_+后缀：1-2位数字 | target="${xml_nfid_block_1}" |
| 跳转至url地址 | 前缀：xml_nfid_url_+后缀：1-2位数字 | params="nodeId=${xml_nfid_url_1}" target="http://www.baidu.com" |
# 移动SDK接入指南
- Android 接入指南
1.请确保你的SDK为最新版本
compile 'com.qiyukf.unicorn:unicorn:3.10.0'
2.在SDK初始化时，为 YSFOptions 的 onBotEventListener 赋值：
// ... your codes
// YSFOptions options = new YSFOptions();
options.onBotEventListener = new OnBotEventListener() {
@Override
public boolean onUrlClick(Context context, String url) {
// 加入处理一触即达url的代码
BrowserActivity.start(context, url);
return true;
}
};
// Unicorn.init(this, "appKey", options, new UnicornImageLoader());
// ... your codes
- IOS 接入指南
1.需要的 iOS SDK 版本是 v3.10.0 或以上
2.自定义 bot 点击事件处理：
QYCustomActionConfig *actionConfig = [[QYSDK sharedSDK] customActionConfig];
//botClick 是 bot 相关点击回调
actionConfig.botClick =【你的代码】
# 微信模板消息接入指南
该接口用于将企业发送给用户的资料，以微信模板消息的形式发出。使用该接口前，需要企业的公众号已添加相应的模板，且企业需要按照指定格式提供访问接口，供七鱼获取对应的数据。 通过该接口，七鱼提供了特定业务支持的数据源集。企业设置的模板中支持哪些数据，将对应数据的在模板中的key填入请求中即可完成设置。当用户查询时，七鱼会访问企业提供数据的接口，然后会将对应的数据根据模板配置填入，最后发给用户。
该接口目前仅支持设置物流类的模板信息。
POST请求为：
POST https://qiyukf.com/openapi/settings/wxTemplates?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463216914&checksum=e72be4487b6fc03e0f914fc11e4053d771598d93
Content-Type:application/json;charset=utf-8
其中各参数说明可参见消息接口文档
设置物流类模板信息post请求内容字段列举如下：
{
"appId":"wxcxxxxxxxxx",
"logistic": {
"template_id":"s8BlawhJMXO4YWEvvsrBiBrxuBJzYwpk-HchuAa9jbc",
"top":"first",
"bottom":"remark",
"id": "keyword1",
"name":"keyword2",
"last_state": "keyword3",
"update_time": "keyword4",
"sender":"keyword5",
"sender_site":"keyword6",
"sender_phone":"keyword7",
"receiver":"keyword8",
"receiver_site":"keyword9",
"receiver_phone":"keyword10",
"order_id":"keyword11",
"order_time":"keyword12",
"price":"keyword13",
"status":"keyword14",
"good_name":"keyword15"
}
}
公共字段说明：
| 字段名 | 是否必须 | 说明 |
|---|---|---|
| appId | 是 | 公众号的appId，可在公众号后台查看。 |
| logistic | 否 | 物流类模板信息，物流类必须，其他类无需设置。 |
物流类模板字段说明：
| 字段名 | 是否必须 | 说明 |
|---|---|---|
| template_id | 是 | 该模板的ID, 可在公众号后台看到 |
| top | 否 | 显示在模板消息第一行的内容的key |
| bottom | 否 | 显示在模板消息最后一行的内容的key |
| id | 否 | 物流运单ID的key |
| name | 否 | 快递公司名称的key |
| last_state | 否 | 运单的最新状态 |
| update_time | 否 | 最新状态的更新时间 |
| sender | 否 | 寄件人的key |
| sender_site | 否 | 寄出地址的key |
| sender_phone | 否 | 寄件人联系电话的key |
| receiver | 否 | 收件人的key |
| receiver_site | 否 | 收件地址的key |
| receiver_phone | 否 | 收件人电话的key |
| order_id | 否 | 与运单关联的商品订单ID的key |
| order_time | 否 | 商品下单时间或者寄件时间的key |
| price | 否 | 商品价格或者快递单价格的key |
| status | 否 | 商品订单状态或者运单状态的key |
| good_name | 否 | 商品名称的key |
示例： 某个公众号添加了ID为 s8BlawhJMXO4YWEvvsrBiBrxuBJzYwpk-HchuAa9jbc 的模板，其格式为：
{{first.DATA}}
订单编号：{{keyword1.DATA}}
取件公司：{{keyword2.DATA}}
{{remark.DATA}}
调用设置接口的内容如下：
{
"appId": "wxcxxxxxxx",
"logistic": {
"template_id":"s8BlawhJMXO4YWEvvsrBiBrxuBJzYwpk-HchuAa9jbc",
"top":"first",
"bottom":"remark",
"id": "keyword1",
"name":"keyword2"
}
}
# 呼叫事件对接
呼叫中心用户电话呼入的时候，七鱼系统通过该接口向第三方系统获取用户信息，包括访客VIP级别、外接IVR路由、crm信息，根据获取到的信息进行访客分配，及访客信息更新；IVR过程中，IVR校验以及导航项动作自定义IVR接口和播放内容接口也使用该接口对接；通话结束后，同步通话记录使用该接口对接。通过参数eventtype进行区分。
参数eventtype类型说明：
| 参数值 | 参数说明 |
|---|---|
| 1 | 获取用户信息 |
| 2 | IVR校验 |
| 3 | 自定义IVR接口 |
| 4 | 播放内容接口 |
| 5 | 同步通话记录 |
| 6 | 同步电话服务记录字段 |
七鱼服务器向第三方接口请求信息时，采用密钥安全认证机制，保证第三方系统的信息安全。
# 对接参数说明
# 调用说明
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
curl请求样例如下
1.电话呼入时获取用户信息，包括访客VIP级别、外接IVR路由、crm信息
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 1,
"phone": "15854582215",
"staffphone": "05718669163"
}'
2.IVR校验请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 2,
"phone": "15854582215",
"staffphone": "05718669163",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "2-1-0",
"input": "110226198501272116"
}'
3.IVR过程中自定义IVR接口事件通知
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 3,
"phone": "15854582215",
"staffphone": "05718669163",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "1-3"
}'
4.IVR过程中播放内容接口请求播放内容
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 4,
"phone": "15854582215",
"staffphone": "05718669163",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "1-2"
}'
5.通话结束后同步通话记录请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 5,
"sessionid": 216629286,
"direction": "呼入",
"createtime": 1511832411968,
"connectionbeginetime": 1511832413992,
"connectionendtime": 1511832432183,
"from": "15854582215",
"to": "05718690766",
"user": "云中鹤",
"category": "售后问题/退货",
"staffid": 642656,
"staffname": "丽娜",
"status": "接通",
"visittimes": 1,
"duration": "10:15",
"evaluation": "满意",
"recordurl": "https://ysf.nosdn.127.net/9f670ff01dae290ad4bf83401d291069.wav",
"overflowFrom": "溢出来源",
"shuntGroupName"："分流客服组",
"ivrPath":"ivr路径",
"mobileArea":"号码归属地"
}'
6.通话结束后同步电话服务记录字段请求
curl -X POST \
'http://www.xxx.com/api/ivr/crminfo?checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventtype": 6,
"sessionid": 216629286,
"from": "15854582215",
"to": "05718690766",
"counselCategory":"咨询分类1/咨询分析2/咨询分类3",
"remarks":"咨询小计",
"customValueArray":[
{
"key":"自定义字段1",
"value":"自定义value1"
},
{
"key":"自定义字段2",
"value":"自定义value2"
}
]
}'
# 请求参数和数据校验
七鱼服务器向第三方服务器请求用户信息时，url携带参数checksum和time。
| 参数 | 参数说明 |
|---|---|
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
POST请求body参数为jsonStr格式，例如，当eventtype=2时，POST请求参数样例如下：
{
"eventtype": 2,
"phone": "15854582215",
"sessionid": 216629286,
"ivrid": 3545,
"keyrecord": "2-1-0",
"input": "110226198501272116"
}
| 参数 | 参数说明 |
|---|---|
| eventtype | 请求事件类型，1为请求用户信息 |
| phone | 用户电话号码 |
| staffphone | 客服电话号码，如果存在多个中继号，则为当前使用的中继号 |
| sessionid | 呼叫通话ID，请选择使用 |
| ivrid | IVR模型ID，请选择使用 |
| keyrecord | IVR事件对应按键顺序 |
| input | IVR校验时用户输入值 |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 接口返回数据说明
接口返回数据为JSON格式，最外层参数如下：
| 参数 | 参数说明 |
|---|---|
| code | 错误码。200表示设置成功。 |
| result | code为200时，返回值有效。eventtype=1时返回访客信息，为JSON格式数据；eventtype=4时返回播放内容，为String格式数据；其他可以为空 |
| message | 请求错误时，填错误提示信息 |
当eventtype=1时result 数据格式如下
| 参数 | 是否必须 | 数据类型 | 参数说明 |
|---|---|---|---|
| name | 否 | String | 访客姓名 |
| level | 否 | Int | 访客VIP级别，值为0到10 |
| groupId | 否 | Int | IVR分流客服组ID |
| staffId | 否 | Int | IVR分流客服ID |
| ivrId | 否 | Int | IVR分流到指定IVR |
非VIP用户
level等于0，VIP级别等级为1到10数值groupId和staffId值对应七鱼系统中的客服组ID和客服ID，从七鱼管理系统「设置」->「高级设置」->「访客分配」->「ID查询」中查找获取。ivrId对应七鱼系统中的ivrId，从七鱼管理系统「呼叫中心」->「设置」->「IVR语音导航设置」中查找获取。三种ID的优先级为：staffId->groupId->ivrId。如果只设置了
staffId，七鱼会查找staffId对应的呼叫客服，如果该客服正好空闲的话，电话将优先分配给他。如果设置了
staffId和groupId，七鱼会优先查找staffId对应的呼叫客服，如果该客服正好空闲，电话将优先分配给他，否则系统判断是否有返回groupId值。如果有groupId值，系统再优先查找groupId对应的呼叫客服组进行分配。如果只设置了
groupId，七鱼会优先查找groupId对应的呼叫客服组，如果该客服组内正好有空闲客服，电话将随机分配给空闲的客服。如果该客服组内没有空闲客服，若有溢出规则，则按溢出规则走。如果只设置了
ivrId,七鱼会优先按照ivrId来进行分配,会忽略ivr会员等级分配策略。如果没有返回
staffId、groupId和ivrId三种中的任意一种，或者返回的值不存在，则七鱼将执行一般IVR分流。
返回的完整参数格式如下：
{
"code": 200,
"message": "",
"result": {
"level": 0,
"groupId": 415451,
"staffId": 2164623
}
}
# 第三方接口样例
以SpringMVC框架为例，第三方系统提供的接口如下：
@RequestMapping(value = "/crminfo", method = RequestMethod.POST)
@ResponseBody
public String getClientCrmInfoByPhone(
@RequestParam(value = "checksum", required = true) String checksum,
@RequestParam(value = "time", required = true) String time,
@RequestBody(required = true) String jsonStr
) {
// 此处省略业务代码
}
# 外呼营销任务导入
该接口由七鱼提供，第三方调用该接口可以自动生成营销相关的外呼任务，方便呼叫客服及时联系客户，从而提升营销质量
# 营销接口调用及校验
# 接口调用
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
第三方服务器调用七鱼该接口时，url携带参数appkey, checksum和time。
| 参数 | 参数说明 |
|---|---|
| appKey | 你的企业的appKey |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 营销接口参数说明
POST请求body参数为jsonStr格式，POST请求参数样例如下：
{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
...
...
}
# 参数说明
外呼营销任务导入时，可以选择两种时间模式：
一种是营销事件模式
timeModel=0传递事件发生时间
eventTime和执行时机occasionType，以及相对的执行时间区间relativeStartTime、relativeEndTime，系统根据这些数据计算出真实的外呼任务时间区间。另一种是绝对时间模式
timeModel=1直接传递外呼任务的开始时间
startTime和结束时间endTime
外呼任务的客服类型支持客服和客服组两种模式，当seatType=0，需要同时传递seatIds，当seatType=1，需要同时传递groupIds
具体参数说明如下：
| 参数 | 参数说明 |
|---|---|
| eventType | 请求事件类型，1-用户注册App，2-用户逾期未还款，3-沉默未投资，默认为其他 |
| name | 任务名称 |
| description | 任务描述 |
| timeModel | 时间模式：0-时间规则模式，1-时间段模式 |
| eventTime | 事件发生时间，当timeModel=0时有效 |
| occasionType | 执行时机，0-eventTime之前，1-eventTime之后，当timeModel=0时有效 |
| relativeStartTime | 任务相对开始时间，单位为秒，当timeModel=0时有效 |
| relativeEndTime | 任务相对结束时间，单位为秒，当timeModel=0时有效 |
| startTime | 任务绝对开始时间，当timeModel=1时有效，单位为毫秒 |
| endTime | 任务绝对结束时间，当timeModel=1时有效，单位为毫秒 |
| hideNumber | 是否在外呼任务中隐藏用户号码，0-不隐藏，1-隐藏 |
| seatType | 指定客服类型，0-客服，1-客服分组，2-按客户关系分配 |
| seatIds | 客服的id串，以逗号分隔，当seatType=0时有效 |
| groupIds | 客服组id串，以逗号分隔，当seatType=1时有效 |
| customerInfo | 用户号码信息键值对，为Json数组 |
| customerInfo.name | 用户名 |
| customerInfo.value | 用户手机号 |
| customerInfo.staffId | 客户负责人staffId |
| forecastType | 任务类型, 0:普通外呼任务, 1:自动外呼任务 |
| forecastRate | 自动外呼任务的倍率值,取值范围:0.01 至 2.00, forecastType=1时有效 |
| forecastDids | 自动外呼任务的企业号码DID, 格式为:a,b,c 号码用英文逗号隔开的数组 |
具体响应格式如下:
| 参数 | 参数说明 |
|---|---|
| code | 错误码 |
| message | 错误描述 |
| data | json对象 |
| data.id | 任务ID |
# 营销任务请求样例
curl请求样例如下：
1.当以营销事件相对时间模式传参，即timeModel=0，并且指定分配到客服，即seatType=0时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/marketing?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"timeModel": 0,
"eventTime": 1517722346089,
"occasionType": 1,
"relativeStartTime": 10,
"relativeEndTime": 1440,
"seatType": 0,
"seatIds": "40004,40005",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912"
},
{
"name": "小喽喽",
"value": "15411660066"
}
]
}'
2.当以精确时间模式传参，即timeModel=1，并且指定分配到客服组，即seatType=1时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/marketing?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"timeModel": 1,
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 1,
"groupIds": "62451,511186",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912"
},
{
"name": "小喽喽",
"value": "15411660066"
}
]
}'
3.当以精确时间模式传参，即timeModel=1，并且指定按客户关系分配，即seatType=2时
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/marketing?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"timeModel": 1,
"startTime": 1517722346089,
"endTime": 1517808746089,
"seatType": 2,
"groupIds": "62451,511186",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912"
"staffId": "1234"
},
{
"name": "小喽喽",
"value": "15411660066"
"staffId": "1235"
}
]
}'
1.如果是自动外呼任务时，只需要扩展三项参数即可，其它参数保持不变
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltask/marketing?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
"timeModel": 0,
"eventTime": 1517722346089,
"occasionType": 1,
"relativeStartTime": 10,
"relativeEndTime": 1440,
"seatType": 0,
"seatIds": "40004,40005",
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912"
},
{
"name": "小喽喽",
"value": "15411660066"
}
],
"forecastType":1,
"forecastRate":1.05,
"forecastDids":"057110000000,057110000001,057110000002"
}'
# 外呼营销任务详情导入
该接口由七鱼提供，第三方调用该接口可以补充自动外呼任务的号码，方便呼叫客服及时联系客户，从而提升营销质量
###接口限制条件
- 1、任务类型：自动外呼任务
- 2、任务周期：周期不大于1周的任务
- 3、任务状态：未过期任务
- 4、一次插入条数：小于等于1000条号码
- 5、频次：上一次外呼任务插入未完成，则接口调用失败
# 任务详情导入接口调用及校验
# 接口调用
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
第三方服务器调用七鱼该接口时，url携带参数appkey, checksum和time。
| 参数 | 参数说明 |
|---|---|
| appKey | 你的企业的appKey |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 任务详情导入接口参数说明
POST请求body参数为jsonStr格式，POST请求参数样例如下：
{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
...
...
}
# 参数说明
具体参数说明如下：
| 参数 | 参数说明 |
|---|---|
| taskId | 任务ID |
| customerInfo.name | 客户名称 |
| customerInfo.value | 客户号码 |
具体响应格式如下:
| 参数 | 参数说明 |
|---|---|
| code | 错误码 |
| message | 错误描述 |
# 任务详情导入请求样例
curl请求样例如下：
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/add?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{
"taskId": 1,
"customerInfo": [
{
"name": "阿波罗",
"value": "18957128912"
},
{
"name": "小喽喽",
"value": "15411660066"
}
]
}'
# 外呼营销任务详情获取
该接口由七鱼提供，第三方调用该接口获取任务详情
###接口限制条件
- 1、任务类型：自动外呼任务
- 2、频次：一分钟
# 任务详情获取接口调用及校验
# 接口调用
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
第三方服务器调用七鱼该接口时，url携带参数appkey, checksum和time。
| 参数 | 参数说明 |
|---|---|
| appKey | 你的企业的appKey |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 任务详情获取接口参数说明
POST请求body参数为jsonStr格式，POST请求参数样例如下：
{
"eventType": 1,
"name": "意向客户回访",
"description": "新注册用户回访",
...
...
}
# 参数说明
具体参数说明如下：
| 参数 | 参数说明 |
|---|---|
| taskId | 任务ID |
具体响应格式如下:
| 参数 | 参数说明 |
|---|---|
| code | 错误码 |
| message | 错误描述 |
| data.forecastType | 任务类型，0:预览式外呼, 1:预测式外呼 |
| data.status | 状态 |
| data.customCount | 客户数量 |
| data.staffCount | 客服数量 |
| data.startTime | 开始时间 |
| data.endTime | 结束时间 |
| data.exeCount | 执行数量 |
| data.answerCount | 接通数量 |
# 任务详情获取请求样例
curl请求样例如下：
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/autoCalltask/get?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '1'
# 外呼营销任务详情编辑
该接口由七鱼提供，第三方调用该接口可编辑手动外呼任务详情，减少因为内部原因产生的错误呼出量及对用户体验的伤害
# 接口限制条件
- 1、任务类型：手动外呼任务
- 2、任务状态：待分配，未开始，进行中
- 3、任务明细状态：未呼叫
- 4、一次编辑条数：小于等于100条号码
- 5、一次编辑的影响的任务数：小于等于100个
- 6、频次：上一次外呼任务编辑未完成，则接口调用失败
- 7、数据安全：编辑任务详情时候，会锁定任务。故不要高频操作，3分钟内只能操作一次。
# 任务详情编辑接口调用及校验
# 接口调用
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
第三方服务器调用七鱼该接口时，url携带参数appkey, checksum和time。
| 参数 | 参数说明 |
|---|---|
| appKey | 你的企业的appKey |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 任务详情编辑接口参数说明
POST请求body参数为jsonStr格式，POST请求参数样例如下：
{
"taskId": 1,
"taskDetails": [
{
"id":"1110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"1111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
...
...
}
# 参数说明
具体参数说明如下：
| 参数 | 参数说明 |
|---|---|
| taskId | 任务ID |
| taskDetails | 任务详情 |
| taskDetails.id | 任务详情Id |
| taskDetails.username | 客户名称 |
| taskDetails.phone | 客户电话号码 |
| taskDetails.description | 任务描述 |
具体响应格式如下:
| 参数 | 参数说明 |
|---|---|
| code | 错误码 |
| message | 错误描述 |
任务详情编辑请求样例 curl请求样例如下：
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/delete?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '[
{
"taskId": 1,
"taskDetails": [
{
"id":"1110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"1111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
},{
"taskId": 2,
"taskDetails": [
{
"id":"2110",
"username":"xx",
"phone":"121323423",
"description":"备注"
},{
"id":"2111",
"username":"xx",
"phone":"121323423",
"description":"备注"
}
]
}
]'
# 外呼营销任务详情删除
该接口由七鱼提供，第三方调用该接口可删除手动外呼任务详情，减少由于内部原因产生的错误呼出量及对用户体验的伤害
# 接口限制条件
- 1、任务类型：手动外呼任务
- 2、任务状态：待分配，未开始，进行中
- 3、任务明细状态：未呼叫
- 4、一次删除条数：小于等于100条号码
- 5、一次删除的影响的任务数：小于等于100个
- 6、频次：上一次外呼任务删除未完成，则接口调用失败
- 7、数据安全：删除任务详情时，会锁定任务。故不要高频操作，3分钟内只能操作一次
# 任务详情删除接口调用及校验
# 接口调用
本接口只支持POST请求；
本接口请求Content-Type类型为：application/json;charset=utf-8;
本接口返回类型为JSON，同时进行UTF-8编码。
# 数据校验
第三方服务器调用七鱼该接口时，url携带参数appkey, checksum和time。
| 参数 | 参数说明 |
|---|---|
| appKey | 你的企业的appKey |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
| checksum | SHA1(appSecret + md5 + time)， 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
以上checksum 用于校验数据的完整性，其计算规则中，appSecret 可在七鱼管理页面「设置」->「消息接口」页面找到，md5 为Body参数jsonStr字符串的 md5 哈希值（小写形式），即 md5 = MD5(jsonStr).toLowwerCase()，time 就是请求参数中的 time。处于安全性考虑，每个 checksum 的有效期为 5 分钟，请确认发起请求的服务器是与标准时间同步的，比如有NTP服务。
具体计算 checksum 的 Java 示例代码请参考本页「客户中心数据导入」->「数据校验」中的示例代码
# 任务详情删除接口参数说明
POST请求body参数为jsonStr格式，POST请求参数样例如下：
{
"taskId": 1,
"taskDetailIds": [123,1213],
...
...
}
# 参数说明
具体参数说明如下：
| 参数 | 参数说明 |
|---|---|
| taskId | 任务ID |
| taskDetailIds | 任务详情Ids |
具体响应格式如下:
| 参数 | 参数说明 |
|---|---|
| code | 错误码 |
| message | 错误描述 |
任务详情编辑请求样例 curl请求样例如下：
curl -X POST \
'https://www.qiyukf.com/openapi/ipcc/calltaskdetail/delete?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '[
{
"taskId": 1,
"taskDetailIds": [123,1231]
},{
"taskId": 2,
"taskDetailIds": [1232,12312]
}
]'
# 呼叫工具条
呼叫工具条功能作为一个嵌入式插件提供给需要呼叫工具条的第三方网站使用。建议第三方在需要嵌入的页面加载成功后，通过异步接口向自己服务器端发起请求，获取工具条的SDK地址，并完成工具条SDK加载以及外呼拨号对接后即可使用。在异步接口中，第三方需要根据当前登录的客服，获取客服对应的账号信息，向七鱼发起HttpClient请求，来获取七鱼动态生成的SDK文件地址。前端页面拿到SDK地址之后，将其作为js文件进行加载即可完成工具条的初始化，再配合工具条提供的拨号接口，即可完成工具条功能的接入
# 获取SDK接入地址
第三方向七鱼请求SDK接入地址的时候，七鱼会执行客服在七鱼的登录事件，并生成含动态口令的SDK接入地址返回给第三方
接口调用及数据校验规则参考上面营销接口调用及校验
curl请求样例如下：
curl -X POST \
'http://qiyukf.com/openapi/ipcc/login?appKey=1c088a89de51d0af457616605f28390f&checksum=f570a5eb049eb803b086e45829b07e48&time=1511832531' \
-H 'content-type: application/json;charset=utf-8' \
-d '{"staffName": "admin"}'
请求参数说明
| 参数 | 是否必须 | 数据类型 | 参数说明 |
|---|---|---|---|
| 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 | 动态登录口令 |
# 初始化SDK
前端页面通过上面异步接口获得sdk_url之后，动态加载这个sdk_url对应的js文件，即可完成工具条的初始化
动态加载js样例
var sdk = document.createElement('script');
sdk.async = !0;
sdk.src = url;
sdk.onload = function(){//sdk加载成功后，注册呼叫工具条事件
qiConnect.on({
onload: function() {//呼叫工具条加载完毕的事件通知。此事件完成后才可调用外呼接口
console.log('呼叫工具条加载完毕！');
},
/**
* 建立新呼叫会话的事件，包括外呼和呼入
* @param {Object} session 呼叫会话的session信息
*
* @param {String} session.address 号码归属地
* @param {String} session.usernumber 客户号码
* @param {Number} session.sessionid 会话id
* @param {String} session.staffnumber 坐席号码
* @param {Number} session.staffid 坐席id
* @param {String} session.staffname 坐席账号
* @param {Number} session.direction 会话方向，1表示呼入，2表示呼出
*/
session: function(session){
console.log('session',session);
}
});
};
document.body.appendChild(sdk);
呼叫工具条加载完成后，会在接入页面添加id为CONTAINER-CC-TOOLBAR的工具条容器元素，可通过定义该容器的样式，定制呼叫工具条的位置以及叠放层级。
自定义样式示例
<style>
#CONTAINER-CC-TOOLBAR {
top: 100px;
right: 100px;
z-index: 100001;
}
</style>
# 外呼拨号接口
外呼工具条SDK加载完成后，SDK会在全局对象window上挂载qiConnect对象，该对象实现了外呼接口call，直接调用并传入需要外呼的号码即可。注意：外呼操作需要在onload事件(呼叫功能加载完成)之后才能执行。
使用拨号接口的样例如下
<form onsubmit="return false;" id="yyy">
<p id="call">外呼号码<input type="text" name="mobile" />
<input type="button" value="外呼" name="buttonCall" />
</p>
</form>
document.getElementById('yyy').buttonCall.onclick = function() {
if (!form.mobile.value) return alert('请输入电话号码');
qiConnect.call(form.mobile.value);
}
# 服务先知
当访客链接七鱼机器人时，七鱼服务器会调用第三方预判接口，获取企业对该访客的预判信息，该预判信息会展示在热门问题和一触即达快捷入口处。调用时会将访客的第三方标识id和访客当前所处页面作为参数调用企业预判接口，调用方式如下： 1·使用POST方式请求企业预判接口 2·接口请求的Content-Type为：application/x-www-form-urlencoded;charset=utf-8 3·调用校验，在调用预判接口时，七鱼会将appSecret，time，nonce三个参数使用sha1哈希算法生成checkSum校验和（同消息接口checksum校验和示例代码），其中timestamp为精确到秒的时间戳，nonce为一串随机生成的字符串,参数放在Http Request Header中传输 请求参数说明：
| 参数 | 参数类型 | 参数说明 |
|---|---|---|
| appId | String | 企业分配给七鱼的appId |
| nonce | String | 描述信息 |
| time | Long | 当前UTC时间戳，精确到秒数 |
| checkSum | String | SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time，并转化成16进制的小写字符串作为checkSum |
| userId | String | 开发者的应用里的用户ID，通过CRM接入同步给七鱼 |
| fromPage | String | 访客进入机器人的页面链接 |
| content | String | 访客在机器人会话中发送的单条消息内容 |
- 企业接口返回说明
返回类型为JSON，同时进行UTF-8编码
| 参数 | 数据类型 | 必填 | 说明 |
|---|---|---|---|
| guide | String | 否 | 进入机器人时的引导语，字数上限200个字。如果当前值为空，将依次选择服务先知引导语、常见问题引导语之一作为引导语。当接口仅返回引导语不返回问题时，结果无效。 |
| faq | Array | 否 | 对于放置在问题列表的数据，放在faq这一参数内返回。如果企业faq参数返回不为空，展示 "置顶问题" + faq参数结果；如果企业faq参数返回为空，若设置了常见问题则展示常见问题，若未设置常见问题则展示置顶问题。 |
| bot | Array | 否 | 对于放置在服务直达的数据，放在bot这一参数内返回。最后按顺序依次展示企业返回bot参数、服务先知算法接口(需要开启先知算法开关)、企业运营后台配置参数，重复问题将会被过滤。 |
例：
{
"guide":"欢迎引导语",
"faq": [
"热门问题1",
"热门问题2",
"热门问题3"
],
"bot": [
"查物流",
"查退款",
"查订单"
]
}
# 访客标签信息对接
通过访客标签信息对接，可以实现第三方系统与七鱼系统访客标签信息的同步。客服在七鱼系统修改访客标签时，七鱼会回调第三方接口地址，将标签修改信息通知第三方系统。同时第三方系统在修改访客标签的时候，可以调用七鱼的开放接口，将标签修改同步到七鱼系统。
客户标签信息对接包括三个接口。七鱼提供两个开放接口给第三方查询所有标签信息和接收标签信息修改事件，第三方提供一个标签事件回调接口。
# 获取所有标签信息
该接口由七鱼提供。通过该接口可以获取所有访客标签信息。第三方在获取到访客标签信息后，需要将标签信息存储到本地库中，以便后续标签信息同步时可以快速根据标签id找到对应标签名字。标签同步事件中传递的信息，只有标签id，没有标签名字。
接口调用及数据校验规则参考上面营销接口调用及校验
服务器收到的POST请求样例如下：
POST https://qiyukf.com/openapi/tag/all?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求body内容固定为all，示例如下：
all
响应信息为：
| 参数 | 数据类型 | 参数说明 |
|---|---|---|
| code | Integer | 错误码。200表示设置成功。 |
| message | String | 错误提示信息 |
| result | Json | 认证结果 |
当code=200时，result内容为JsonArray数据，格式如下：
[
{
"id":156656,
"name":"重点客户",
"color":"#eeeeee"
},{
"id":2455485,
"name":"新客户",
"color":"#dddddd"
}
]
# 标签修改开放接口
该接口由七鱼提供。第三方通过该接口可以修改七鱼系统中访客的标签信息。
接口调用及数据校验规则参考上面营销接口调用及校验
服务器收到的POST请求样例如下：
POST https://qiyukf.com/openapi/tag/update?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求body内容如下：
{
"foreignid": "onlyone",
"tag_ids": [156656,2455485],
"type": "save"
}
参数字段说明：
| 参数 | 数据类型 | 参数说明 |
|---|---|---|
| foreignid | String | 访客的foreignid |
| tag_ids | Json | 标签id数组，标签id通过/openapi/tag/all接口查询 |
| type | String | save表示为用户增加对应标签，delete表示从用户标签中删除对应标签。 |
响应信息为：
| 参数 | 数据类型 | 参数说明 |
|---|---|---|
| code | Integer | 错误码。200表示设置成功。 |
| message | String | 错误提示信息 |
| result | Json | 修改后的用户最终全部标签id数组 |
当code=200时，result内容为JsonArray数据，格式如下：
[156656,2455485]
# 标签事件回调接口
该接口由第三方提供。第三方企业需在页面：接入设置->信息对接->CRM信息对接->客户标签接口URL 处填写提供的接口地址。七鱼会在访客标签信息修改时回调该接口，将修改信息同步给第三方。
接口调用及数据校验规则参考上面七鱼用户认证机制的认证接口章节
第三方服务器收到的POST请求样例如下：
POST https://xxx.com/xxx/xxx?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求body内容如下：
{
"userid": 12451558,
"foreignid": "onlyone",
"tag_ids": [156656,2455485],
"type": "save"
}
参数字段说明：
| 参数 | 数据类型 | 参数说明 |
|---|---|---|
| foreignid | String | 访客的foreignid |
| userid | Long | 访客在七鱼的id |
| tag_ids | Json | 标签id数组，标签id通过/openapi/tag/all接口查询 |
| type | String | save表示为用户增加对应标签，delete表示从用户标签中删除对应标签。 |
响应信息为：
| 参数 | 数据类型 | 参数说明 |
|---|---|---|
| code | Integer | 错误码。200表示设置成功。 |
| message | String | 错误提示信息 |
# 访客名片信息推送
当七鱼系统使用者主动修改访客名片，或者系统访客访问行为触发系统自动修改访客名片时，七鱼会通过此接口主动向七鱼的用户企业服务器推送数据
###接口使用说明
首先需要填写推送消息接收接口地址，请在 设置->接入设置->信息对接->访客名片接口URL 处填写
编写接口
- 接口鉴权 参阅《消息接口文档》
- 接口类型 POST
- 接口参数 主要用于鉴权
参数 参数说明 checksum SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) time 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 4.接口数据 接口返回数据在请求体内，主要是以JSON格式返回一个访客名片对象
数据键名 数据类型 数据说明 name String 名字 phone String 电话 foreign_id String 外部id address Integer 地址 vipLevel String VIP等级 foreign_id String 外部id remarks String 备注 first_contact_time Long 首次联系时间 last_contact_time Long 最后联系时间 first_session_time Long 首次会话时间 last_session_time Long 上次会话时间 customField Map<Long, Object> 自定义属性值id tagsDetail Map<Long, String> TagId和名称
# 客服质量报表api
提供客服工作报表-客服-工作质量对应企业一个月的过去一个月的数据
###接口使用说明
请求样例
curl -X POST \ 'http://www.xxx.com/openapi/statistic/staffquality?appKey=3ec34a7ab5305ff49959d5c5023ccabf&time=1534316797&checksum=9b924c7adac9d31a6177fae51cdd86f0e7dee4da' \ -H 'content-type: application/json;charset=utf-8'编写接口
- 接口鉴权 参阅《消息接口文档》
- 接口类型 POST
- 接口参数 主要用于鉴权
参数 参数说明 appKey 企业的appKey checksum SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) time 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 4.接口数据 接口返回数据在请求体内，主要是以JSON格式返回
数据键名 数据类型 数据说明 id Long 客服id name String 客服名字 namePinyin String 客服名字拼音 avgFirstRespTime Long 平均首响 avgRespTime Long 平均响应时长 replyRatio Double 应答率 avgTime Long 平均会话时长 evaRatio Double 参评率 satisfactionRatio 满意度 备注 role Integer 客服角色 timestamp Long 时间 evaluationDetail String 满意度详情 dynamicTitle Map<Integer, Integer> 动态满意度详情 answerReplyRatio Double 答问比 oneOffRatio Double 一次性解决率
# 行为轨迹接入
发送数据主动推送用户行为轨迹
###接口使用说明
请求接口：http://qiyukf.com/openapi/track/event/set
POST http://qiyukf..com/openapi/track/event/set?appKey=3ec34a7ab5305ff49959d5c5023ccabf
&time=1534316797&checksum=9b924c7adac9d31a6177fae51cdd86f0e7dee4da
- 接口鉴权 参阅《消息接口文档》
- 接口类型 POST
- 接口参数 主要用于鉴权
| 参数 | 参数说明 |
|---|---|
| appKey | 企业的appKey |
| checksum | SHA1(appSecret + md5 + time), 三个参数拼接的字符串，进行SHA1哈希计算，转化成16进制字符(String，小写) |
| time | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
4.接口数据 接口返回数据在请求体内，主要是以JSON格式返回
| 数据键名 | 数据类型 | 数据说明 |
|---|---|---|
| foreignId | String | 第三方系统内用户的唯一表示id,字符串 |
| time | Long | 行为时间，与url上的time有区别，url的time用于鉴权，这个time用于记录行为发生的时间 |
| title | String | 行为title，当行为缩略显示时，仅显示其title |
| desc | String | 行为具体描述，描述行为的情况，请传入Json对象，每个key-value会成对展示在界面上，注意本身在一个Json对象内传输数据，双引号要用转义符转义 |
请求body内容如下：
{
"foreignId": "abc175",
"time": 1534238116999,
"title": "示例",
"desc": "{\"abc\":\"cde\"}"
}