七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
客户管理CRM 对接

CRM 对接概述

CRM 对接方式、错误码和用户认证机制。

概述

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

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

  • 轻量对接是指通过 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)。

对接方式对比与建议

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

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

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

对比角度轻量对接接口对接
数据来源发起会话时,客户端通过 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字段,提供用于显示的错误信息。

七鱼用户认证机制

概述

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

术语

  • 第三方:接入七鱼的企业
  • uid:第三方的用户唯一标识

认证过程

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

实施流程

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

认证模式说明

认证模式需要联系技术支持进行修改,目前支持如下几种认证模式:

  • 模式0:不做校验,直接使用上传的foreignId,允许foreignId为空
  • 模式1:如果有authToken和foreignId才校验authToken是否有效,如果authToken校验失败则不允许申请会话
  • 模式2:如果有foreignId,则必须同时有authToken,并且校验authToken是否有效,如果authToken校验失败则不允许申请会话
  • 模式3:必须有foreignId,如果有authToken才校验authToken是否有效,如果authToken校验失败则不允许申请会话
  • 模式4:必须有foreignId和authToken,并且校验authToken是否有效,如果authToken校验失败则不允许申请会话
  • 模式5:没有foreignId和authToken,也去三方校验,如果校验失败则不允许申请会话

授权接口

生成随机授权码authToken的接口。该接口由第三方自己调用。

如果该接口由第三方自己调用,需要第三方自己保证生成的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参数示例

{"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":true}

响应字段

字段含义
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参数:

  1. ysf('config') 设置 authToken 属性
  2. 调用 pollAuthToken 或 setAuthToken 设置 authToken 值

pollAuthToken(url, options)

接口描述

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

  1. 第三方自定义获取token的api的接口
  2. 更新防止 token 失效
请求说明
 GET [http://domain/api/getAuthToken](http://domain/api/getAuthToken) // 获取token的第三方的Api接口
 Content-Type : application/x-www-form-urlencoded;charset=utf-8
参数说明
intervalNumber是轮询时间间隔
retryTimeNumber否重试次数,默认为4次
dataObject否请求参数
methodString否GET
onsuccessFunction否成功回调 code==200才进入此回调
onerrorFunction否失败回调
intervalNumber是轮询时间间隔
    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
参数说明
codeNumber状态码
messageString返回消息说明
resultObject{authToken : ''} authToken必填
codeNumber状态码

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。

这篇文档有帮助吗?

目录