阿里云客服在线服务开放接口接入指南

云客服” class=”reference-link”>1 访客->云客服

Java接入示例demo代码: [接入示例代码]demo

php接入示例demo代码: [接入示例代码]demo

<a name="1.1 统一发送消息接口” class=”reference-link”>1.1 统一发送消息接口

访客消息分为普通消息（文本，图片，语音等）和事件消息（请求人工服务，访客主动离线，服务评价等）接口统一如下：

接口调用说明

• 该接口只支持POST请求
• Content-Types请求头设置为：application/json;charset=utf-8；

对下面URL发送POST请求即可：

https://cschat-ccs.aliyun.com/openapi/forwardMessage?tntInstId=XXX&scene=YYY&src=outerservice&timestamp=1487230487910&digest=ZZZ

注意替换URL中对应的参数值，参数说明如下：

注意 : 在线服务系统还会校验请求的时间有效性，每个请求的有效期是 2 分钟，所以请确保产生 URL 请求参数 timestamp 的时效性。

<a name="1.2 发送普通消息” class=”reference-link”>1.2 发送普通消息

普通消息只支持：文本消息，图片消息，语音消息, 文件消息。

1.2.1 发送文本消息

请求 body 内容（JSON 格式），示例数据及说明如下。

{
   "userId": "12345",
   "msgType": "text",
   "content": "hello world",
   "timestamp": 1487230487910
}

注意：请务必将时间戳设置在当前时间，否则消息会被认为过期而拒收。

1.2.2 发送图片消息

note ：图片消息需要先调用上传文件接口获得文件的 filekey，然后将 filekey 放到 content 字段 POST。获取 filekey 请参考：文件上传接口。

• 请求 body 内容（JSON 格式），示例数据及说明如下。

{
   "userId": "12345",
   "msgType": "image",
   "content": "filekey",
   "timestamp": 1487230487910
}

1.2.3 发送语音消息

note: 语音消息需要先调用 上传文件接口获得文件的filekey，然后将filekey放到content字段POST。获取fileky请参考： 文件上传接口

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "voice",
   "content": "filekey",
   "timestamp": 1487230487910
}

1.2.4 发送文件消息

注意：文件消息需要先调用上传文件接口获得文件的 filekey，然后将 filekey 放到 content 字段 POST。获取 filekey 请参考： 文件上传接口。

• 请求 body 内容（JSON 格式），示例数据及说明如下。

{
   "userId": "12345",
   "msgType": "file",
   "content": "filekey",
   "timestamp": 1487230487910
}

1.2.5 发送普通消息接口返回说明

• 请求body内容 (json格式), 示例数据及说明如下

• 接口调用返回内容

{
    "code": "200",
    "msg": "success"
}

• 参数说明

如果返回响应码不是成功，需要租户ISV根据自身业务情况进行一定次数的重试。

<a name="1.3 发送事件消息” class=”reference-link”>1.3 发送事件消息

事件消息支持：请求人工服务，访客主动离线，服务评价。

1.3.1 请求人工服务

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "CONNECT_SERVER",
   "skillGroupId" : 101, //要连接人工客服的技能组 id (非必须)
   "timestamp": 1487230487910
}

1.3.2 访客主动离线

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "VISITOR_OFFLINE",
   "timestamp": 1487230487910
}

1.3.3 服务评价

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "VISITOR_FEEDBACK",
   "feedbackScore": "0",
   "feedbackMsg": "pretty good",
   "timestamp": 1487230487910
}

note : 可以对会话开始6个小时之内的人工服务进行评价 ( 进行中会话和已经离线都可以 ).

1.3.4 发送事件消息接口返回说明

• 请求body内容 (json格式), 示例数据及说明如下

• 接口调用返回内容

{
    "code": "200",
    "msg": "success"
}

• 参数说明

如果返回响应码不是成功，需要租户ISV根据自身业务情况进行一定次数的重试。

访客” class=”reference-link”>2 云客服->访客

<a name="2.1 统一消息接收接口” class=”reference-link”>2.1 统一消息接收接口

当云客服回复普通消息或者通知访客事件消息的时候，需要由租户提供接收消息接口地址，云客服会统一向下面的接口发送POST请求：

云客服消息分为普通消息（文本消息，图片消息等）和事件消息（达到转人工条件，会话建立，会话超时提醒，会话转接，会话关闭等）接口统一如下：

接口调用说明

• 所有请求为POST请求
• Content-Types请求头设置为：application/json;charset=utf-8；

接口地址（由租户提供本地址)：

https://OUTER_SERVICE_CALLBACK_URL?timestamp=1487230487910&digest=xxxxxx

该接口配置在云客服工作台左侧菜单栏的配置管理中. 其配置方式同其他配置相同, 配置例子如下:

note : 配置名称自己定义, 配置编码固定为: OUTER_SERVICE_CALLBACK_URL, 配置值: 请写自己公网的接口地址(后面不要带任何参数).

<a name="2.2 接收普通消息” class=”reference-link”>2.2 接收普通消息

支持：文本消息，图片消息

2.2.1 接收文本消息

 {
   "userId": "12345",
"msgType": "text",
"content": "hello world",
"timestamp": 1487230487910,
"serverName": "客服007"
}

2.2.2 接收知识库消息

 {
      "userId": "12345",
"msgType": "knowledge",
"content": "hello world",
      "knowledge" : {
        "addword": "",
        "askReply": null,
        "askback": "",
        "chatUuid": "201711130013010702409800648137",
        "correct": false,
        "disKnowledges": [],
        "intentId": 0,
        "knowledge": { //此为知识库内容
            "attachments": [],
            "catId": 29102,
            "catIdPath": "1,29100,29101,29102",
            "catTitlePath": "云客服实例,账户资产,余额宝,余额宝介绍",
            "content": "<h1>余额宝介绍：<span>具体内容 富文本</span></h1>", //知识库的富文本内容( html 格式)
            "extTitles": [
                "余额宝介绍"
            ],
            "feats": "",
            "id": 88889038, //知识库 id, 通过此可以获取知识库的网页展示链接
            "libraryId": 1,
            "score": 0.75249994,
            "srcScore": 4.442274,
            "title": "余额宝介绍" //知识库标题
        },
        "payload": "",
        "propId": 0,
        "question": "余额宝",
        "questionId": "",
        "segment": "余额宝",
        "sessionUuid": "201711130013010700407300839603",
        "speech": "余额宝介绍： 余额宝是支付宝推出的一项余额理财产品。",
        "subKnowledges": [
            {
                "attachments": [],
                "catId": 0,
                "catIdPath": "",
                "catTitlePath": "",
                "content": "",
                "extTitles": [
                    "余额宝回报介绍",
                    "余额宝收益介绍",
                    "余额宝利润介绍"
                ],
                "feats": "{\"originalExtCharSegStr\":\"余 额 宝 回 报 介 绍\",\"finalExtStemStr\":\"余额宝 回报 介绍\",\"finalSegStr\":\"余额宝 收益 介绍\",\"finalStemStr\":\"余额宝 利息 介绍\",\"originalExtSegStr\":\"余额宝 回报 介绍\",\"originalCharSegStr\":\"余 额 宝 收 益 介 绍\",\"originalSegStr\":\"余额宝 收益 介绍\",\"finalExtSegStr\":\"余额宝 回报 介绍\"}",
                "id": 88889043, //相关问题的知识库id, 可以通过此获取该知识点的网页访问链接.
                "libraryId": 1,
                "score": 0.6161795,
                "srcScore": 3.701895,
                "title": "余额宝收益介绍" //可能相关的问题
            },
            {
                "attachments": [],
                "catId": 0,
                "catIdPath": "",
                "catTitlePath": "",
                "content": "",
                "extTitles": [
                    "余额宝大额转入"
                ],
                "feats": "{\"originalExtCharSegStr\":\"余 额 宝 大 额 转 入\",\"finalExtStemStr\":\"余额宝 大额 转入\",\"finalSegStr\":\"余额宝 大额 转入\",\"finalStemStr\":\"余额宝 大额 转入\",\"originalExtSegStr\":\"余额宝 大额 转入\",\"originalCharSegStr\":\"余 额 宝 大 额 转 入\",\"originalSegStr\":\"余额宝 大额 转入\",\"finalExtSegStr\":\"余额宝 大额 转入\"}",
                "id": 88889048, //相关问题的知识库id, 可以通过此获取该知识点的网页访问链接.
                "libraryId": 1,
                "score": 0.6027196,
                "srcScore": 3.8734581,
                "title": "余额宝大额转入" //可能相关的问题
            }
        ],
        "termination": false,
        "type": "QA_CHAT"
    } //知识库回答
"timestamp": 1487230487910,
"serverName": "客服007"
}

note : 知识库的内容展示相对复杂, 如果不需要展示知识库的富文本内容以及相关问题的内容, 可是当做 text 回答来处理. 其中 content 的内容是知识库的文字版本(无配图 无超链接)

2.2.3 接收图片消息

 {
   "userId": "12345",
"msgType": "image",
"content": "fileKey",
"timestamp": 1487230487910,
"serverName": "客服007"
}

2.2.4 接收文件消息

请求 body 内容（JSON 格式），示例数据及说明如下。

 {
      "userId": "12345",
"msgType": "file",
"content": "fileKey",
"timestamp": 1487230487910,
"serverName": "客服007"
}

2.2.5 接收普通消息接口返回说明

该服务需要在10秒内返回一个空字符串(尽量简短，比如空字符串)。

""  //正确返回示例

消息重发

• 响应时间超过10秒, 在线服务会重发该消息(最多重发3次)
• 如果返回字符串为: fail, 在线服务会重发该消息(最多重发3次)

"fail" //重发示例

<a name="2.3 接收事件消息” class=”reference-link”>2.3 接收事件消息

包括以下事件消息：

1. 达到转人工条件
2. 人工会话建立
3. 会话超时提醒
4. 会话转接
5. 会话关闭

2.3.1 达到转人工条件

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "CONNECT_SERVER_ENTRY",
   "content": "达到转人工条件",
   "skillGroup" : [
                               {
                                      "skillGroupId" : 101, //技能组 id
                                      "skillGroupName": "技能组1" //技能组名称
                               },
                               {
                                     "skillGroupId" : 102,
                                     "skillGroupName": "技能组2"
                               }
                           ],
   "timestamp": 1487230487910
}

2.3.2 人工会话建立

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "CONVERSATION_CREATE",
   "content": "您好，我是客服007，很高兴为您服务。",
　 "serverName": "客服007" ,
   "timestamp": 1487230487910
}

2.3.3 会话超时提醒

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "VISITOR_OVERTIME_NOTICE",
   "content" : "请尽快回复,否则对话将在一定时间后自动结束~",
   "timestamp": 1487230487910
}

2.3.4 会话转接

transferType: SYSTEM, MANUAL eventMsg:

• 请求body内容 (json格式), 示例数据及说明如下

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "CONVERSATION_TRANSFER",
   "transferType" : "SYS_OVERTIME_BROKEN / SWITCH_AND_OFF / SELF_FORCE_OFFLINE",
   "content": "会话转接中",
   "timestamp": 1487230487910
}

2.3.5 会话关闭

请求 body 内容（JSON 格式），示例数据及说明如下。

{
   "userId": "12345",
   "msgType": "event",
   "eventType": "CONVERSATION_CLOSE",
   "closeType" : "SERVER_CLOSE/OVERTIME_CLOSE",
   "content" : "超时关闭",
   "timestamp": 1487230487910
}

2.3.6 接收事件消息接口返回说明

该服务需要在 10 秒内返回一个空字符串（或尽量简短其他字符串）。

""  //正确返回示例

消息重发：

• 响应时间超过 10 秒，在线服务会重发该消息（最多重发 3 次）。
• 如果返回字符串为 fail，在线服务会重发该消息（最多重发 3 次）。

"fail" //重发示例

3 文件上传

在与云客服在线平台交互的时候，统一通过json数据进行交互。在遇到文件类型的交互的时候（例如图片消息，语音消息，访客上传文件)需要进行文件上传。对于媒体文件的上传分为普通文件上传(File) 以及 Base64格式文件上传(String)

<a name="3.1 普通文件上传” class=”reference-link”>3.1 普通文件上传

文件支持类型如下：

3.1.1 上传文件接口调用

对下面URL发送POST请求即可 (FORM表单: Header: form-data ) ：

https://cschat-ccs.aliyun.com/openapi/uploadFile?tntInstId=XXX&src=outerservice&timestamp=1487230487910&digest=ZZZ

请注意替换URL中对应的参数值，参数说明如下：

• POST Body内容使用 form-data 表单.

3.1.2 上传文件接口返回

• 成功返回-Json数据：

{
   "type":"image",
   "filekey":"file_key",
   "timestamp":123456789
}

• 成功返回参数说明

• 失败返回-Json数据：

{
   "code":40004, //错误码
   "msg":"invalid file type"
}

• 失败返回参数说明

3.1.3 上传文件内容摘要计算

见摘要计算：摘要计算方法

<a name="3.2 Base64方式上传” class=”reference-link”>3.2 Base64方式上传

文件支持类型如下：

3.2.1 base64方式上传接口调用

对下面URL发送POST请求即可 (FORM表单: Header: form-data ) ：

https://cschat-ccs.aliyun.com/openapi/uploadFile?tntInstId=XXX&src=outerservice&timestamp=1487230487910&digest=ZZZ

请注意替换URL中对应的参数值，参数说明如下：

• POST Body内容

使用Form-data表单.

3.2.2 base64方式上传接口返回

• 成功返回-Json数据：

{
   "type":"image"
   "filekey":"file_key",
   "timestamp":123456789
}

• 成功返回参数说明

• 失败返回-Json数据：

{
   "code":40004, //错误码
   "msg":"invalid file type"
}

• 失败返回参数说明

3.2.3 base64方式上传内容摘要计算

见摘要计算：base64文件上传摘要计算

<a name="3.3 文件获取接口” class=”reference-link”>3.3 文件获取接口

文件获取接口支持文件文件类型同上传接口相同。

3.3.1 文件获取接口调用 (GET)

对下面URL发送GET请求即可：

https://cschat-ccs.aliyun.com/openapi/fetchFile?tntInstId=XXX&src=outerservice&timestamp=1487230487910&digest=ZZZ&fileKey=123.jpg

3.3.2 文件获取接口返回

• 成功返回 – JSON 数据：

{
    "timestamp": 1508496632427,
    "fileKey": "38f5485c-c0b4-41f8-901e-eb44147a41d7test.jpg",
    "url": "http://knowledge-inner.cn-hangzhou.oss.jiuzhou.cloud.aliyun-inc.com/38f5485c-c0b4-41f8-901e-eb44147a41d7test.jpg?Expires=1508500232&OSSAccessKeyId=YXghJmYltg9n0ndF&Signature=jzNY17ZKUZSxWsG0axM9hFy/4/M%3D"
}

• 成功返回的参数说明

• 失败返回 – JSON 数据

{
   "code":404, //错误码
   "msg":"file not found"
}

• 失败返回的参数说明

4 摘要计算方法

摘要计算(hmac_sha1)所需密钥由云客服提供（收集租户tntInstId和当前文档链接，提工单给我们的同学），租户(ISV) 需妥善保存。出于安全考虑，在线服务系统每次接收到消息后，都会对消息的数据完整性进行一次校验。在线服务系统会按照同样的规则重复进行一次hmac_sha1计算，并将计算结果和URL请求参数中的digest比对，二者相等才算通过验证。

note: 请确认加密的内容是否和发送post的body内容一致, 字段排列顺序也要保持一致否则会出现校验失败

<a name="4.1 普通消息摘要计算方法” class=”reference-link”>4.1 普通消息摘要计算方法

普通消息(以及事件消息)摘要计算函数示例代码:

下面代码是java代码. 其他版本: c#计算摘要

    import javax.crypto.spec.SecretKeySpec;
    import javax.crypto.Mac;
    /**
     * hmac_sha1算法计算内容摘要
     *
     * value的生成流程请看详细文档对于不同的消息类型构造方式不同
     * <ul>
     *   <li>文本消息：toJSONString( MessageContent ) + timestamp</li>
     *   <li>base64文件：base64字符串 + timestamp</li>
     * </ul>
     *
     * @param value 原始数据的字符串
     * @param keyBytes   密钥
     * @return 加密后的字符串
     */
    public String hmac_sha1(String value, byte[] keyBytes) {
        try {
            SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1");
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(signingKey);
            byte[] rawHmac = mac.doFinal(value.getBytes("utf-8"));
            String digest = toHexString(rawHmac);
            return digest;
        } catch (Exception ex) {
            return null;
        }
    }
            /**
     * 二进制字节数组转十六进制
     *
     * @param v 二进制数组内容
     * @return 十六进制字符串
     */
    public  String toHexString(byte[] v) {
        String HEX_DIGITS               = "0123456789abcdef";
        StringBuilder sb = new StringBuilder(v.length * 2);
        for (int i = 0; i < v.length; i++) {
            int b = v[i] & 0xFF;
            sb.append(HEX_DIGITS.charAt(b >>> 4)).append(
                HEX_DIGITS.charAt(b & 0xF));
        }
        return sb.toString();
    }

消息数据校验（digest 计算方法）

digest=hmac_sha1(消息内容字符串 + 时间戳，String key)

1. 请保证发送的消息体字符串和计算摘要的消息字符串完全一致
2. 消息内容字符串和时间戳字符串拼接前后顺序不能改变

• 消息内容：POST Body 的 JSON 序列化成 String；
• 时间戳：URL 内的 timestamp

 /** 样例 */
//初始化时间戳 由于后台会判断时间戳有效期 请一定使用当前时间戳
long timestamp = System.currentTimeMillis();
//序列化消息体
String requestContentStr = JSONObject.toJSONString(messageContent);
//生成签名
String digest = hmac_sha1(requestContentStr + timestamp, key);
// 其中 key 是由云客服颁发的密钥

<a name="4.2 事件消息摘要计算方法” class=”reference-link”>4.2 事件消息摘要计算方法

同4.1普通消息计算方法相同

<a name="4.3 文件上传摘要计算” class=”reference-link”>4.3 文件上传摘要计算

文件摘要计算函数示例代码:

    import javax.crypto.spec.SecretKeySpec;
    import javax.crypto.Mac;
    /**
     * hmac_sha1算法计算内容摘要
     *
     * 主要用于二进制的文件摘要计算
     * <ul>
     *     <li>二进制文件消息： byte[] file + byte timestamp </li>
     * </ul>
     * @param bytes 需要加密的二进制数组
     * @param keyBytes 私钥
     * @return 加密后的字符串
     */
    private String hmac_sha1(byte[] bytes, byte[] keyBytes) {
        try {
            SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1");
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(signingKey);
            byte[] rawHmac = mac.doFinal(bytes);
            String digest = toHexString(rawHmac);
            return digest;
        } catch (Exception ex) {
            return null;
        }
    }
        /**
     * 二进制字节数组转十六进制
     *
     * @param v 二进制数组内容
     * @return 十六进制字符串
     */
    public  String toHexString(byte[] v) {
        String HEX_DIGITS               = "0123456789abcdef";
        StringBuilder sb = new StringBuilder(v.length * 2);
        for (int i = 0; i < v.length; i++) {
            int b = v[i] & 0xFF;
            sb.append(HEX_DIGITS.charAt(b >>> 4)).append(
                HEX_DIGITS.charAt(b & 0xF));
        }
        return sb.toString();
    }

4.3.1 普通文件上传摘要计算

消息数据校验（digest 计算方法）

digest=hmac_sha1(文件转为 byte 数组 + 时间戳的 byte 数组，String key)

1. 时间戳的byte数组是通过时间戳字符串转换为byte数组,不是数字转换为byte数组.
2. 消息内容byte数组拼接前后顺序不能改变

计算方法：将文件转为 byte 数组，与时间戳的 byte 数组拼接在一起计算 hmac_sha1。

MultipartFile file; //上传的文件
Long timestamp = System.currentTimeMillis();
byte[] fileBytes = file.getBytes();
byte[] timeBytes = String.valueOf(timestamp).getBytes();
byte[] digestBytes = ArrayUtils.addAll(fileBytes, timeBytes);
String digest = hmac_sha1(digestBytes, key);
// 其中 key 是由云客服颁发的密钥

4.3.2 base64文件上传摘要计算

计算方法同普通文件上传相同。

将 Base64 的字符串转为 byte 数组，与时间戳的 byte 数组拼接在一起计算 hmac_sha1。

String base64File; //上传文件base64字符串
long timestamp = System.currentTimeMillis();
byte[] fileBytes = base64File.getBytes();
byte[] timeBytes = String.valueOf(timestamp).getBytes();
byte[] digestBytes = ArrayUtils.addAll(fileBytes, timeBytes);
String digest = hmac_sha1(digestBytes, key);
// 其中 key 是由云客服颁发的密钥

<a name="4.4 文件获取摘要计算” class=”reference-link”>4.4 文件获取摘要计算

通过将 filekey 和时间戳拼接在一起, 进行摘要计算 hamc_sha1.

 String fileKey = "fileKey.jpg";
 long timestamp = System.currentTimeMillis();
 String digest = hmac_sha1(fileKey + timestamp, key);
 // 其中 key 是由云客服颁发的密钥

5 错误码对照表

下表为错误码说明：