全部产品
弹性计算 会员服务 网络 安全 移动云 数加·大数据分析及展现 数加·大数据应用 管理与监控 云通信 阿里云办公 培训与认证 更多
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 智能硬件

在线服务开放接口接入指南

更新时间:2018-04-13 12:36:32

1 访客->云客服

示例demo代码: 接入示例代码

1.1 统一发送消息接口

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

接口调用说明

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

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

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

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

URL参数 说明
tntInstId 租户id,由云客服提供
scene 聊天窗编码,由云客服提供
timestamp 请求时的Unix时间戳(毫秒),自行获取当前时间戳,计算摘要使用
digest 请求体内容摘要,用于消息安全校验,计算方法见摘要计算方法
src 消息渠道名称,固定为:outerservice

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

1.2 发送普通消息

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

1.2.1 发送文本消息

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

  1. {
  2. "userId": "12345",
  3. "msgType": "text",
  4. "content": "hello world"
  5. "timestamp": 1487230487910
  6. }
json 参数 说明
userId 用户的唯一标识,比如可以是微信中用户的 openid
msgType 文本消息类型:text
content 消息内容为一个字符串
timestamp 消息发送时的 UNIX 时间戳(毫秒)

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

1.2.2 发送图片消息

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

  • 请求 body 内容(JSON 格式),示例数据及说明如下。
  1. {
  2. "userId": "12345",
  3. "msgType": "image",
  4. "content": "filekey",
  5. "timestamp": 1487230487910
  6. }
json 参数 说明
userId 用户的唯一标识,比如可以是微信中用户的 openid
msgType 图片消息类型:image
content 消息内容为图片的 filekey
timestamp 消息发送时的 UNIX 时间戳(毫秒)

1.2.3 发送语音消息

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

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "voice",
  4. "content": "filekey",
  5. "timestamp": 1487230487910
  6. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 语音消息类型: voice
content 消息内容为语音文件的filekey
timestamp 消息发送时的UNIX时间戳(毫秒)

1.2.4 发送文件消息

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

  • 请求 body 内容(JSON 格式),示例数据及说明如下。
  1. {
  2. "userId": "12345",
  3. "msgType": "file",
  4. "content": "filekey",
  5. "timestamp": 1487230487910
  6. }
JSON 参数 说明
userId 用户的唯一标识,比如可以是微信中用户的 openid
msgType 文件消息类型:file
content 消息内容为文件的 filekey
timestamp 消息发送时的 UNIX 时间戳(毫秒)

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

  • 请求body内容 (json格式), 示例数据及说明如下
  • 接口调用返回内容
  1. {
  2. "code": "200",
  3. "msg": "success"
  4. }
  • 参数说明
code msg 说明
200 success 调用成功
其他 错误消息提醒 调用失败 (具体错误码请看 错误码定义 )

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

1.3 发送事件消息

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

1.3.1 请求人工服务

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "CONNECT_SERVER",
  5. "skillGroupId" : 101, //要连接人工客服的技能组 id (非必须)
  6. "timestamp": 1487230487910
  7. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType CONNECT_SERVER 请求人工服务
skillGroupId 技能组 id (如果是单技能组,可以不传. 多技能组必须传)
timestamp 消息发送时的UNIX时间戳(毫秒)

1.3.2 访客主动离线

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "VISITOR_OFFLINE",
  5. "timestamp": 1487230487910
  6. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType VISITOR_OFFLINE 访客主动离线
timestamp 消息发送时的UNIX时间戳(毫秒)

1.3.3 服务评价

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "VISITOR_FEEDBACK",
  5. "feedbackScore": "0",
  6. "feedbackMsg": "pretty good",
  7. "timestamp": 1487230487910
  8. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType VISITOR_FEEDBACK 服务评价
feedbackScore {0:非常满意, 1:满意, 2:一般, 3:不满意} 满意度评分
feedbackMsg 评价内容
timestamp 消息发送时的UNIX时间戳(毫秒)

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

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

  • 请求body内容 (json格式), 示例数据及说明如下
  • 接口调用返回内容
  1. {
  2. "code": "200",
  3. "msg": "success"
  4. }
  • 参数说明
code msg 说明
200 success 调用成功
其他 错误消息提醒 调用失败 (具体错误码请看 错误码定义)

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


2 云客服->访客

2.1 统一消息接收接口

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

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

接口调用说明

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

接口地址(由租户提供本地址):

  1. https://OUTER_SERVICE_CALLBACK_URL?timestamp=1487230487910&digest=xxxxxx
URL参数 说明
timestamp 请求时的Unix时间戳(毫秒),自行获取当前时间戳,计算摘要使用
digest 请求体内容摘要,用于消息安全校验,计算方法见摘要计算方法

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

OUTER_SERVICE_CALLBACK_URL

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

2.2 接收普通消息

支持:文本消息,图片消息

2.2.1 接收文本消息

  1. {
  2. "userId": "12345",
  3.   "msgType": "text",
  4.   "content": "hello world",
  5.   "timestamp": 1487230487910,
  6.   "serverName": "客服007"
  7. }
参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 文本消息类型 : text
content 文本消息内容
timestamp 消息发送时的UNIX时间戳(毫秒)
serverName 客服姓名

2.2.2 接收知识库消息

  1. {
  2. "userId": "12345",
  3.   "msgType": "knowledge",
  4.   "content": "hello world",
  5. "knowledge" : {
  6. "addword": "",
  7. "askReply": null,
  8. "askback": "",
  9. "chatUuid": "201711130013010702409800648137",
  10. "correct": false,
  11. "disKnowledges": [],
  12. "intentId": 0,
  13. "knowledge": { //此为知识库内容
  14. "attachments": [],
  15. "catId": 29102,
  16. "catIdPath": "1,29100,29101,29102",
  17. "catTitlePath": "云客服实例,账户资产,余额宝,余额宝介绍",
  18. "content": "<h1>余额宝介绍:<span>具体内容 富文本</span></h1>", //知识库的富文本内容( html 格式)
  19. "extTitles": [
  20. "余额宝介绍"
  21. ],
  22. "feats": "",
  23. "id": 88889038, //知识库 id, 通过此可以获取知识库的网页展示链接
  24. "libraryId": 1,
  25. "score": 0.75249994,
  26. "srcScore": 4.442274,
  27. "title": "余额宝介绍" //知识库标题
  28. },
  29. "payload": "",
  30. "propId": 0,
  31. "question": "余额宝",
  32. "questionId": "",
  33. "segment": "余额宝",
  34. "sessionUuid": "201711130013010700407300839603",
  35. "speech": "余额宝介绍: 余额宝是支付宝推出的一项余额理财产品。",
  36. "subKnowledges": [
  37. {
  38. "attachments": [],
  39. "catId": 0,
  40. "catIdPath": "",
  41. "catTitlePath": "",
  42. "content": "",
  43. "extTitles": [
  44. "余额宝回报介绍",
  45. "余额宝收益介绍",
  46. "余额宝利润介绍"
  47. ],
  48. "feats": "{\"originalExtCharSegStr\":\"余 额 宝 回 报 介 绍\",\"finalExtStemStr\":\"余额宝 回报 介绍\",\"finalSegStr\":\"余额宝 收益 介绍\",\"finalStemStr\":\"余额宝 利息 介绍\",\"originalExtSegStr\":\"余额宝 回报 介绍\",\"originalCharSegStr\":\"余 额 宝 收 益 介 绍\",\"originalSegStr\":\"余额宝 收益 介绍\",\"finalExtSegStr\":\"余额宝 回报 介绍\"}",
  49. "id": 88889043, //相关问题的知识库id, 可以通过此获取该知识点的网页访问链接.
  50. "libraryId": 1,
  51. "score": 0.6161795,
  52. "srcScore": 3.701895,
  53. "title": "余额宝收益介绍" //可能相关的问题
  54. },
  55. {
  56. "attachments": [],
  57. "catId": 0,
  58. "catIdPath": "",
  59. "catTitlePath": "",
  60. "content": "",
  61. "extTitles": [
  62. "余额宝大额转入"
  63. ],
  64. "feats": "{\"originalExtCharSegStr\":\"余 额 宝 大 额 转 入\",\"finalExtStemStr\":\"余额宝 大额 转入\",\"finalSegStr\":\"余额宝 大额 转入\",\"finalStemStr\":\"余额宝 大额 转入\",\"originalExtSegStr\":\"余额宝 大额 转入\",\"originalCharSegStr\":\"余 额 宝 大 额 转 入\",\"originalSegStr\":\"余额宝 大额 转入\",\"finalExtSegStr\":\"余额宝 大额 转入\"}",
  65. "id": 88889048, //相关问题的知识库id, 可以通过此获取该知识点的网页访问链接.
  66. "libraryId": 1,
  67. "score": 0.6027196,
  68. "srcScore": 3.8734581,
  69. "title": "余额宝大额转入" //可能相关的问题
  70. }
  71. ],
  72. "termination": false,
  73. "type": "QA_CHAT"
  74. } //知识库回答
  75.   "timestamp": 1487230487910,
  76.   "serverName": "客服007"
  77. }
参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 文本消息类型 : knowledge
content 文本消息内容
knowledge 知识库的回答 如果需要展示知识库的回答使用此内容
timestamp 消息发送时的UNIX时间戳(毫秒)
serverName 客服姓名

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

2.2.3 接收图片消息

  1. {
  2. "userId": "12345",
  3.   "msgType": "image",
  4.   "content": "fileKey",
  5.   "timestamp": 1487230487910,
  6.   "serverName": "客服007"
  7. }
参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 消息类型 : image
content 消息内容 : 图片的fileKey 通过调用文件获取接口来获取文件访问下载链接
timestamp 消息发送时的UNIX时间戳(毫秒)
serverName 客服姓名

2.2.4 接收文件消息

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

  1. {
  2. "userId": "12345",
  3.   "msgType": "file",
  4.   "content": "fileKey",
  5.   "timestamp": 1487230487910,
  6.   "serverName": "客服007"
  7. }
参数 说明
userId 用户的唯一标识,比如可以是微信中用户的 openid
msgType 消息类型:file
content 消息内容:文件的 fileKey 通过调用 文件获取接口 来获取文件访问下载链接
timestamp 消息发送时的 UNIX 时间戳(毫秒)
serverName 客服姓名

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

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

  1. "" //正确返回示例

消息重发

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

2.3 接收事件消息

包括以下事件消息:

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

2.3.1 达到转人工条件

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "CONNECT_SERVER_ENTRY",
  5. "content": "达到转人工条件",
  6. "skillGroup" : [
  7. {
  8. "skillGroupId" : 101, //技能组 id
  9. "skillGroupName": "技能组1" //技能组名称
  10. },
  11. {
  12. "skillGroupId" : 102,
  13. "skillGroupName": "技能组2"
  14. }
  15. ],
  16. "timestamp": 1487230487910
  17. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType CONNECT_SERVER_ENTRY
content 默认文案
skillGroup 聊天窗的技能组列表(购买云客服之后, 创建聊天窗的时候配置)
timestamp 消息发送时的UNIX时间戳(毫秒)

2.3.2 人工会话建立

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "CONVERSATION_CREATE",
  5. "content": "您好,我是客服007,很高兴为您服务。",
  6.   "serverName": "客服007" ,
  7. "timestamp": 1487230487910
  8. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType CONVERSATION_CREATE
content 会话建立的默认文案
serverName 客服姓名
timestamp 消息发送时的UNIX时间戳(毫秒)

2.3.3 会话超时提醒

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "VISITOR_OVERTIME_NOTICE",
  5. "content" : "请尽快回复,否则对话将在一定时间后自动结束~",
  6. "timestamp": 1487230487910
  7. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType VISITOR_OVERTIME_NOTICE
content 会话超时提醒的默认文案
timestamp 消息发送时的UNIX时间戳(毫秒)

2.3.4 会话转接

transferType: SYSTEM, MANUAL eventMsg:

  • 请求body内容 (json格式), 示例数据及说明如下
  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "CONVERSATION_TRANSFER",
  5. "transferType" : "SYS_OVERTIME_BROKEN / SWITCH_AND_OFF / SELF_FORCE_OFFLINE",
  6. "content": "会话转接中",
  7. "timestamp": 1487230487910
  8. }
json参数 说明
userId 用户的唯一标识,比如可以是微信中用户的openid
msgType 事件消息类型: event
eventType CONVERSATION_TRANSFER
transferType SYS_OVERTIME_BROKEN 客服断线导致的系统转接,SWITCH_AND_OFF 客服手动转接,SELF_FORCE_OFFLINE 客服下线导致的系统转接
content 会话转接的默认文案
timestamp 消息发送时的UNIX时间戳(毫秒)

2.3.5 会话关闭

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

  1. {
  2. "userId": "12345",
  3. "msgType": "event",
  4. "eventType": "CONVERSATION_CLOSE",
  5. "closeType" : "SERVER_CLOSE/OVERTIME_CLOSE",
  6. "content" : "超时关闭",
  7. "timestamp": 1487230487910
  8. }
JSON 参数 说明
userId 用户的唯一标识,比如可以是微信中用户的 openid
msgType 事件消息类型:event
eventType offline 用户主动下线
eventMsg 提示内容
closeType SERVER_CLOSE 客服主动关闭;OVERTIME_CLOSE 超时关闭
timestamp 消息发送时的 UNIX 时间戳(毫秒)

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

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

  1. "" //正确返回示例

消息重发:

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

3 文件上传

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

3.1 普通文件上传

文件支持类型如下:

文件类型 文件最大限制 说明
图片(image) 2M 支持PNG\JPEG\JPG\GIF格式
语音(voice) 2M 播放长度不超过60s,支持格式:amr\mp3\ogg\wav

3.1.1 上传文件接口调用

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

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

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

URL参数 说明
tntInstId 租户id,由云客服提供
timestamp 请求时的Unix时间戳(毫秒),自行获取
digest 请求体内容摘要,用于消息安全校验,文件摘要计算方法
src 消息渠道名称,固定为:outerservice
  • POST Body内容使用 form-data 表单.
参数 是否必须 说明
type 图片(image), 语音(voice), 视频(video)
file 要上传的文件
fileName 要上传的文件名
timestamp 当前时间戳

3.1.2 上传文件接口返回

  • 成功返回-Json数据:
  1. {
  2. "type":"image",
  3. "filekey":"file_key",
  4. "timestamp":123456789
  5. }
  • 成功返回参数说明
参数 类型 说明
type String 该文件的类型
fileKey String 该文件在云客服存储的fileKey
timestamp Long 上传时间戳 (毫秒)
  • 失败返回-Json数据:
  1. {
  2. "code":40004, //错误码
  3. "msg":"invalid file type"
  4. }
  • 失败返回参数说明
参数 类型 说明
code Long 接口返回错误码
msg String 调用失败信息

3.1.3 上传文件内容摘要计算

见摘要计算:摘要计算方法

3.2 Base64方式上传

文件支持类型如下:

文件类型 文件最大限制 说明
图片(image) 2M 支持PNG\JPEG\JPG\GIF格式
语音(voice) 2M 播放长度不超过60s,支持格式:amr\mp3\ogg\wav

3.2.1 base64方式上传接口调用

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

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

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

URL参数 说明
tntInstId 租户id,由云客服提供
timestamp 请求时的Unix时间戳(毫秒),自行获取
digest 请求体内容摘要,用于消息安全校验,计算方法见 base64文件摘要计算
src 消息渠道名称,固定为:outerservice
  • POST Body内容

使用Form-data表单.

参数 是否必须 说明
type 图片(image), 语音(voice), 视频(video)
base64File 要上传的文件Base64字符串
fileName 要上传的文件名
timestamp 当前时间戳

3.2.2 base64方式上传接口返回

  • 成功返回-Json数据:
  1. {
  2. "type":"image"
  3. "filekey":"file_key",
  4. "timestamp":123456789
  5. }
  • 成功返回参数说明
参数 类型 说明
type String 该文件的类型
fileKey String 该文件在云客服存储的fileKey
timestamp Long 上传时间戳 (毫秒)
  • 失败返回-Json数据:
  1. {
  2. "code":40004, //错误码
  3. "msg":"invalid file type"
  4. }
  • 失败返回参数说明
参数 类型 说明
code Long 接口返回错误码
msg String 调用失败信息

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

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

3.3 文件获取接口

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

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

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

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

3.3.2 文件获取接口返回

  • 成功返回 - JSON 数据:
  1. {
  2. "timestamp": 1508496632427,
  3. "fileKey": "38f5485c-c0b4-41f8-901e-eb44147a41d7test.jpg",
  4. "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"
  5. }
  • 成功返回的参数说明
参数 类型 说明
timestamp Long 响应时间戳
url String 文件的临时访问/下载 URL 3天有效期
fileKey String 请求的的fileKey
  • 失败返回 - JSON 数据
  1. {
  2. "code":404, //错误码
  3. "msg":"file not found"
  4. }
  • 失败返回的参数说明
参数 类型 说明
code Long 错误码 参考: 错误码对照表
msg String 错误提示消息

4 摘要计算方法

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

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

4.1 普通消息摘要计算方法

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

  1. import javax.crypto.spec.SecretKeySpec;
  2. import javax.crypto.Mac;
  3. /**
  4. * hmac_sha1算法计算内容摘要
  5. *
  6. * value的生成流程请看详细文档对于不同的消息类型构造方式不同
  7. * <ul>
  8. * <li>文本消息:toJSONString( MessageContent ) + timestamp</li>
  9. * <li>base64文件:base64字符串 + timestamp</li>
  10. * </ul>
  11. *
  12. * @param value 原始数据的字符串
  13. * @param keyBytes 密钥
  14. * @return 加密后的字符串
  15. */
  16. public String hmac_sha1(String value, byte[] keyBytes) {
  17. try {
  18. SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1");
  19. Mac mac = Mac.getInstance("HmacSHA1");
  20. mac.init(signingKey);
  21. byte[] rawHmac = mac.doFinal(value.getBytes("utf-8"));
  22. String digest = toHexString(rawHmac);
  23. return digest;
  24. } catch (Exception ex) {
  25. return null;
  26. }
  27. }
  28. /**
  29. * 二进制字节数组转十六进制
  30. *
  31. * @param v 二进制数组内容
  32. * @return 十六进制字符串
  33. */
  34. public String toHexString(byte[] v) {
  35. String HEX_DIGITS = "0123456789abcdef";
  36. StringBuilder sb = new StringBuilder(v.length * 2);
  37. for (int i = 0; i < v.length; i++) {
  38. int b = v[i] & 0xFF;
  39. sb.append(HEX_DIGITS.charAt(b >>> 4)).append(
  40. HEX_DIGITS.charAt(b & 0xF));
  41. }
  42. return sb.toString();
  43. }

消息数据校验(digest 计算方法)

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

  1. 请保证发送的消息体字符串和计算摘要的消息字符串完全一致
  2. 消息内容字符串和时间戳字符串拼接前后顺序不能改变
  • 消息内容:POST Body 的 JSON 序列化成 String;
  • 时间戳:URL 内的 timestamp
  1. /** 样例 */
  2. //初始化时间戳 由于后台会判断时间戳有效期 请一定使用当前时间戳
  3. long timestamp = System.currentTimeMillis();
  4. //序列化消息体
  5. String requestContentStr = JSONObject.toJSONString(messageContent);
  6. //生成签名
  7. String digest = hmac_sha1(requestContentStr + timestamp, key);
  8. // 其中 key 是由云客服颁发的密钥

4.2 事件消息摘要计算方法

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

4.3 文件上传摘要计算

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

  1. import javax.crypto.spec.SecretKeySpec;
  2. import javax.crypto.Mac;
  3. /**
  4. * hmac_sha1算法计算内容摘要
  5. *
  6. * 主要用于二进制的文件摘要计算
  7. * <ul>
  8. * <li>二进制文件消息: byte[] file + byte timestamp </li>
  9. * </ul>
  10. * @param bytes 需要加密的二进制数组
  11. * @param keyBytes 私钥
  12. * @return 加密后的字符串
  13. */
  14. private String hmac_sha1(byte[] bytes, byte[] keyBytes) {
  15. try {
  16. SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1");
  17. Mac mac = Mac.getInstance("HmacSHA1");
  18. mac.init(signingKey);
  19. byte[] rawHmac = mac.doFinal(bytes);
  20. String digest = toHexString(rawHmac);
  21. return digest;
  22. } catch (Exception ex) {
  23. return null;
  24. }
  25. }
  26. /**
  27. * 二进制字节数组转十六进制
  28. *
  29. * @param v 二进制数组内容
  30. * @return 十六进制字符串
  31. */
  32. public String toHexString(byte[] v) {
  33. String HEX_DIGITS = "0123456789abcdef";
  34. StringBuilder sb = new StringBuilder(v.length * 2);
  35. for (int i = 0; i < v.length; i++) {
  36. int b = v[i] & 0xFF;
  37. sb.append(HEX_DIGITS.charAt(b >>> 4)).append(
  38. HEX_DIGITS.charAt(b & 0xF));
  39. }
  40. return sb.toString();
  41. }

4.3.1 普通文件上传摘要计算

消息数据校验(digest 计算方法)

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

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

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

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

4.3.2 base64文件上传摘要计算

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

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

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

4.4 文件获取摘要计算

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

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

5 错误码对照表

下表为错误码说明:

code msg 错误说明
501 msg format error 消息格式不符合规范,检查消息体
502 msg process error 通用消息处理异常,可重试或联系云客服技术
503 msg digest error 消息安全校验失败
504 msg expire error 消息过期,检查时间戳
505 init context error 云客服内部异常,可重试或联系云客服技术
506 query scene info error 云客服内部异常,可重试或联系云客服技术
507 init robot error 云客服内部异常,可重试或联系云客服技术
508 not service time 当前非在线人工服务时间,检查在线人工服务的服务时间配置
509 connect manual error 连接人工客服失败,检查是否有客服在线
510 file upload error 上传文件失败
511 event msg type error 不支持的文件类型
512 find context error 找不到对应的上下文
513 feedback error 评价失败 可重试或联系云客服技术
514 visitor offline error 下线失败
515 visitor status error 访客上下文状态handler查找失败
516 connect manual status error 不符合转人工状态
517 key not exist 未申请密钥,联系技术人员生成
本文导读目录