Skip to main content

openAPI 接入文档

接口鉴限说明

获取token

openAPI相关接口使用OAuth2协议认证,获取token方式参考:如何认证

使用token

调用接口时需要在header中设置Authorization。

示例:

POST https://openapi.icsoc.net/chat/v1/message/init_session
Authorization: Bearer f763deae8eb9eca2e507f7463340f66381c0d21c

接口列表

1.创建会话

请求地址:

POST https://openapi.icsoc.net/chat/v1/message/init_session

请求参数示例:

{
"uid": "85fa9dd1-9a16-4d57-884e-a7bf282b7842",
"username": "Davion.Ratke",
"sex": 0,
"channelKey": "7ce0ba6ea9ea0f04dbb8d8a727252fb8",
"ip": "8.29.140.237",
"headImgUrl": "http://jira.icsoc.net/secure/projectavatar?avatarId=10324"
}

响应示例:

{
"code": 0,
"msg": "成功",
"data": {
"sid": "ee4275b5ddf60a1bca65925d8f6b7a74"
}
}

请求参数说明

字段名类型必填说明备注
uidstring开发者应用里的用户ID唯一
usernamestring用户昵称
headImgUrlstring用户头像
channelKeystring渠道keychannelKey、agentId、queueId不能同时为空;channelKey为空时使用全局默认的配置
sexint性别 (0:男,1:女)
ipStringip地址
provincestring所属省不传由ip解析
citystring所属市同上
agentIdlong坐席id会话路由优先级:agentId>queueId>channelKey
queueIdlong技能组id同上
vipintvip等级(1~99)
userDatamap用户定义变量

响应参数说明

字段名类型说明备注
sidstring会话id

2.发送消息

请求地址:

POST https://openapi.icsoc.net/chat/v1/message/send

请求接口如果返回code=20002(表示会话未创建)时,需要先请求init_session(创建会话)接口,返回成功后重新请求该接口。

发送文本消息示例:

{
"uid": "4890e94f2c2e61ff37dc9cd287f8ddcb",
"msgType": "text",
"content":"在吗",
"customMsgId": 1662700987
}

发送视频消息示例:

{
"uid": "4890e94f2c2e61ff37dc9cd287f8ddc",
"msgType": "file",
"content":"/intelcc/2022-09-09/temp-54f3b315a1a446908d326603316a4523.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220909T021213Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=LTAITvoR84zcCiiJ%2F20220909%2Foss-cn-beijing%2Fs3%2Faws4_request&X-Amz-Signature=7e79baaaf10075d6e3bc60497c515bda9881e6e486646e287e2198b3e687bead",
"customMsgId":1662700988
}

撤回消息示例:

{
"uid": "4890e94f2c2e61ff37dc9cd287f8ddcb",
"msgType": "withdraw",
"content":"2209090000052"
}

请求参数说明:

字段名类型必填说明备注
uidstring开发者应用里的用户ID
customMsgIdlong自定义消息id(唯一)为空不能做消息去重
msgTypestring消息类型 (text:文本 image:图片 video:视频 voice:语音 file:文件 withdraw:消息撤回 end:结束会话)
contentstring消息内容(该字段长度最大为 3000 个字符)1.msgType=end时字段可为空,其他情况下均不能为空; 2.msgType=image、video、voice、file时传对应的文件url。请确保该url不会存在跨域访问问题,否则请使用下面的文件上传接口将文件上传,然后使用返回的path;3.msgType=withdraw时传msgId;

响应示例:

{
"code": 0,
"msg": "成功",
"data": {
"sid": "ed4ccbb2e45e96d1acabf1f497ec5c09",
"msgId": 2209190000005
}
}

响应参数说明:

字段名类型说明备注
sidstring会话id
msgIdstring消息id

3.查询评价配置

请求地址:

GET https://openapi.icsoc.net/chat/v1/evaluate/query

请求参数示例:

?channelKey=7ce0ba6ea9ea0f04dbb8d8a727252fb8

说明:channelKey可为空,为空则返回企业默认配置

响应示例:

{
"code": 0,
"msg": "成功",
"data": {
"guide": "您好,请对本次会话进行评价,谢谢!34",
"description": "您的意见是我们努力的方向~(选填)",
"enableDescription": true,
"options": [
{
"optionName": "不满意,非常失望",
"optionOrder": 1,
"optionTags": "服务差,态度差",
"tagRequired": true
},
{
"optionName": "不满意,不开心",
"optionOrder": 2,
"optionTags": "态度敷衍",
"tagRequired": true
},
{
"optionName": "一般,还行吧",
"optionOrder": 3,
"optionTags": "一般般",
"tagRequired": true
},
{
"optionName": "满意,不错",
"optionOrder": 4,
"optionTags": "还不错呢",
"tagRequired": false
},
{
"optionName": "满意,点个赞",
"optionOrder": 5,
"optionTags": "",
"tagRequired": false
}
]
}
}

响应说明:

字段名类型说明备注
guidestring评价提示语
enableDescriptionbool评价描述开关
descriptionbool评价描述
options
optionNamebool选项名称
optionOrderstring选项序号
optionTagsstring评价标签(使用英文逗号分隔)
tagRequiredbool标签是否必填

4.提交评价

请求地址:

POST https://openapi.icsoc.net/chat/v1/evaluate/submit

请求参数示例:

{
"sid": "dc2b5883-dc84-4219-89e1-cd6d7087b236",
"description": "非常好",
"optionOrder": 5,
"optionTags": "服务周到,响应快"
}

请求参数说明:

字段名类型必填说明备注
sidstring会话id
descriptionstring评价描述内容(最大长度500)
optionOrderstring选项序号
optionTagsstring评价标签 英文逗号分隔

响应示例:

{
"code": 0,
"msg": "成功"
}

响应说明:

字段名类型说明备注
codeint状态码(0:表示成功)
msgstring响应消息

5.事件通知

请求地址:

配置在ekt系统的【在线设置】->【其他设置】 中。

具体配置如下:

image

说明:

  1. 只有消息推送开关开启后,才会推送事件消息事件。
  2. 消息支持AES加密,如果是加密消息,接口的content-type为application/octet-stream,请从流数据中读取消息,并通过配置的加密token解密消息。

事件消息参数示例:

{
"createTime": 1661221751,
"msgId": 2208230000009,
"fromType": 0,
"eventType": "MSG_SYS_S_HINT",
"msgContent": "会话开始,接入会话"
}

请求参数说明:

字段名类型必填说明备注
createTimelong创建时间
msgIdlong消息id
fromTypeint事件来源 (0:系统 1:用户 2:坐席 3:机器人 4:模拟坐席发送)
eventTypestring事件类型 ,支持的类型见事件通知列表
sidstring会话id
msgContentstring消息内容

接收明文事件消息示例:

    @PostMapping("/event/callBack")
public void callBack(@RequestParam String eventType, @RequestBody EventCallBackReq req) {
//TODO: 处理业务逻辑
}

接收加密事件消息示例:

    @PostMapping("/event/callBack")
public void callBackWithEncryptMsg(@RequestParam String eventType,HttpServletRequest request) throws Exception {
ServletInputStream inputStream = request.getInputStream();
String token = this.getEncryptToken();
byte[] bytes = inputStream.readAllBytes();
String strReq = new String(AESUtils.decrypt(bytes, token));
JsonNode jsonNode = JsonUtil.getJsonNode(strReq);
//TODO: 处理业务逻辑
}

6.提交留言

用户收到eventType=MSG_SYS_S2C_LEAVEMSG类型的事件后方可提交留言。

请求地址:

POST https://openapi.icsoc.net/chat/v1/leave_msg/submit

请求参数示例:

{
"sid": "ee57d5c8bb57a91c3f63eced3dfde018",
"context": "测试留言xxx"
}

请求参数说明:

字段名类型必填说明备注
sidstring会话id
contextstring留言内容(最大长度500字符)

响应示例:

{
"code": 0,
"msg": "成功"
}

响应说明:

字段名类型说明备注
codeint状态码(0:表示成功)
msgstring响应消息

7.查询会话记录

支持按msgId查向前查询,每次最多返回20条消息记录。

请求地址:

GET https://openapi.icsoc.net/chat/v1/message/list

请求参数示例:

?uid=5890e94f2c2e61ff37dc91d287f8ddca&msgId=3909020000001

请求参数说明:

字段名类型必填说明备注
uidstring开发者应用里的用户ID
msgIdstring上一页最小的msgId

响应示例:

{
"code": 0,
"msg": "成功",
"data": [
{
"msgId": "2209070000136",
"sid": "e910b893d296e534e7a647b1d3e4976a",
"createTime": "1662530414",
"content": "亲,很高兴为您服务,请问有什么可以帮助您!",
"fromType": 4,
"toType": 1,
"errorCode": null,
"errorString": null,
"msgType": 301,
"status": 0,
"agentId": "1038945",
"msgChannel": "0"
},
{
"msgId": "2209070000142",
"sid": "e910b893d296e534e7a647b1d3e4976a",
"createTime": "1662530594",
"content": "您好,未能收到您的回复,本次对话将自动结束hh",
"fromType": 0,
"toType": 1,
"errorCode": null,
"errorString": null,
"msgType": 201,
"status": 0,
"agentId": "",
"msgChannel": "0"
}
]
}

响应说明:

字段名类型说明备注
msgIdstring消息id
sidstring会话id
createTimestring创建时间
contentstring内容
fromTypeint消息来源(0:系统 1:用户 2:坐席 3:机器人 4:模拟坐席发送)
toTypeint消息接收方
errorCodestring错误码
errorStringstring错误说明
agentIdstring坐席id

8.文件上传

请求地址:

POST https://openapi.icsoc.net/chat/v1/file/upload

请求参数示例:

curl --location --request POST 'https://openapi.icsoc.net/chat/v1/file/upload' \
--header 'Authorization: Bearer d79d538177c15e3cd1997d2e1d5575af04acb4b8' \
--form 'file=@"/Users/icsoc/Downloads/car.png"'

请求参数说明:

字段名类型必填说明备注
filefile待上传的文件最大不超过20MB

响应示例:

 {
"code": 0,
"msg": "成功",
"data": {
"path": "/intelcc/2022-09-07/%E7%82%9C%E6%B4%9B%20-%20%E5%BF%83%E4%B8%AD%E7%9A%84%E6%98%9F%E5%85%89-3f9a792825004d5e8c7eb20001dd8f72.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220907T115735Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=LTAITvoR84zcCiiJ%2F20220907%2Foss-cn-beijing%2Fs3%2Faws4_request&X-Amz-Signature=dd9104ae68f5f66c7e5ada2a6cf2f67971c11e81156de2506d674d26205043b0"
}
}

响应说明:

字段名类型说明备注
pathstring文件路径

事件列表

事件类型(eventType)事件编码(code)说明备注
MSG_SYS_S2C_NAVI101导航菜单
MSG_SYS_S2C_NAVI102排队提示语
MSG_SYS_S2C_NAVI103去评价
MSG_SYS_S2C_LEAVEMSG104去留言用户收到该事件后方可提交留言
MSG_SYS_S2C_RECALL105消息撤回坐席撤销消息后会收到该事件
MSG_SYS_S_HINT200系统提示语
MSG_SYS_S2U_HINT201系统提示语(包含欢迎语,超时结束、客服主动结束会话等)
MSG_CHAT_TEXT301纯文本、表情消息
MSG_CHAT_IMG302图片消息
MSG_CHAT_FILE303文件消息
MSG_CHAT_VIDEO304视频消息
MSG_CHAT_VOICE305语音消息
MSG_CHAT_FAQ_YUWEN318机器人FAQ
MSG_SES_INIT_USER701匹配坐席信息推送给用户
MSG_SES_STATUS_CHANGE703会话结束通知用户