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"
    }
}

请求参数说明

字段名	类型	必填	说明	备注
uid	string	是	开发者应用里的用户ID	唯一
username	string		用户昵称
headImgUrl	string		用户头像
channelKey	string		渠道key	channelKey、agentId、queueId不能同时为空；channelKey为空时使用全局默认的配置
sex	int		性别（0:男，1：女）
ip	String		ip地址
province	string		所属省	不传由ip解析
city	string		所属市	同上
agentId	long		坐席id	会话路由优先级：agentId>queueId>channelKey
queueId	long		技能组id	同上
vip	int		vip等级（1~99）
userData	map		用户定义变量

响应参数说明

字段名	类型	说明	备注
sid	string	会话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"
}

请求参数说明:

字段名	类型	必填	说明	备注
uid	string	是	开发者应用里的用户ID
customMsgId	long		自定义消息id（唯一）	为空不能做消息去重
msgType	string	是	消息类型 (text：文本 image：图片 video：视频 voice：语音 file:文件 withdraw:消息撤回 end：结束会话)
content	string		消息内容（该字段长度最大为 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
    }
}

响应参数说明：

字段名	类型	说明	备注
sid	string	会话id
msgId	string	消息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
            }
        ]
    }
}

响应说明：

字段名	类型	说明
guide	string	评价提示语
enableDescription	bool	评价描述开关
description	bool	评价描述
options
optionName	bool	选项名称
optionOrder	string	选项序号
optionTags	string	评价标签(使用英文逗号分隔)
tagRequired	bool	标签是否必填

4.提交评价

请求地址：

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

请求参数示例：

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

请求参数说明:

字段名	类型	必填	说明
sid	string	是	会话id
description	string		评价描述内容(最大长度500)
optionOrder	string	是	选项序号
optionTags	string		评价标签英文逗号分隔

响应示例：

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

响应说明：

字段名	类型	说明	备注
code	int	状态码（0：表示成功）
msg	string	响应消息

5.事件通知

请求地址：

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

具体配置如下：

说明：

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

事件消息参数示例：

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

请求参数说明:

字段名	类型	必填	说明
createTime	long	是	创建时间
msgId	long	是	消息id
fromType	int	是	事件来源（0：系统 1：用户 2：坐席 3：机器人 4：模拟坐席发送）
eventType	string	是	事件类型，支持的类型见事件通知列表
sid	string	是	会话id
msgContent	string	是	消息内容

接收明文事件消息示例：

    @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"
}
请求参数说明:
字段名类型必填说明备注
sid string 是会话id
context string 是留言内容（最大长度500字符）
响应示例：
{
    "code": 0,
    "msg": "成功"
}
响应说明：
字段名类型说明备注
code int 状态码（0：表示成功）
msg string 响应消息

7.查询会话记录

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

请求地址：

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

请求参数示例：

?uid=5890e94f2c2e61ff37dc91d287f8ddca&msgId=3909020000001

请求参数说明:

字段名	类型	必填	说明	备注
uid	string	是	开发者应用里的用户ID
msgId	string	是	上一页最小的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"
        }
    ]
}

响应说明：

字段名	类型	说明
msgId	string	消息id
sid	string	会话id
createTime	string	创建时间
content	string	内容
fromType	int	消息来源（0：系统 1：用户 2：坐席 3：机器人 4：模拟坐席发送）
toType	int	消息接收方
errorCode	string	错误码
errorString	string	错误说明
agentId	string	坐席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"'

请求参数说明:

字段名	类型	必填	说明	备注
file	file	是	待上传的文件	最大不超过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"
    }
}

响应说明：

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

事件列表

事件类型（eventType)	事件编码（code）	说明	备注
MSG_SYS_S2C_NAVI	101	导航菜单
MSG_SYS_S2C_NAVI	102	排队提示语
MSG_SYS_S2C_NAVI	103	去评价
MSG_SYS_S2C_LEAVEMSG	104	去留言	用户收到该事件后方可提交留言
MSG_SYS_S2C_RECALL	105	消息撤回	坐席撤销消息后会收到该事件
MSG_SYS_S_HINT	200	系统提示语
MSG_SYS_S2U_HINT	201	系统提示语（包含欢迎语，超时结束、客服主动结束会话等）
MSG_CHAT_TEXT	301	纯文本、表情消息
MSG_CHAT_IMG	302	图片消息
MSG_CHAT_FILE	303	文件消息
MSG_CHAT_VIDEO	304	视频消息
MSG_CHAT_VOICE	305	语音消息
MSG_CHAT_FAQ_YUWEN	318	机器人FAQ
MSG_SES_INIT_USER	701	匹配坐席信息推送给用户
MSG_SES_STATUS_CHANGE	703	会话结束通知用户

字段名	类型	必填	说明	备注
sid	string	是	会话id
context	string	是	留言内容（最大长度500字符）

接口鉴限说明​

获取token​

使用token​

接口列表​

1.创建会话​

请求地址：​

请求参数示例：​

响应示例：​

请求参数说明​

响应参数说明​

2.发送消息​

请求地址：​

发送文本消息示例：​

发送视频消息示例：​

撤回消息示例：​

请求参数说明:​

响应示例：​

响应参数说明：​

3.查询评价配置​

请求地址：​

请求参数示例：​

响应示例：​

响应说明：​

4.提交评价​

请求地址：​

请求参数示例：​

请求参数说明:​

响应示例：​

响应说明：​

5.事件通知​

请求地址：​

具体配置如下：​

说明：​

事件消息参数示例：​

请求参数说明:​

接收明文事件消息示例：​

接收加密事件消息示例：​

6.提交留言​

请求地址：​

请求参数示例：​

请求参数说明:​

响应示例：​

响应说明：​

7.查询会话记录​

请求地址：​

请求参数示例：​

请求参数说明:​

响应示例：​

响应说明：​

8.文件上传​

请求地址：​

请求参数示例：​

请求参数说明:​

响应示例：​

响应说明：​

事件列表​

接口鉴限说明

获取token

使用token

接口列表

1.创建会话

请求地址：

请求参数示例：

响应示例：

请求参数说明

响应参数说明

2.发送消息

请求地址：

发送文本消息示例：

发送视频消息示例：

撤回消息示例：

请求参数说明:

响应示例：

响应参数说明：

3.查询评价配置

请求地址：

请求参数示例：

响应示例：

响应说明：

4.提交评价

请求地址：

请求参数示例：

请求参数说明:

响应示例：

响应说明：

5.事件通知

请求地址：

具体配置如下：

说明：

事件消息参数示例：

请求参数说明:

接收明文事件消息示例：

接收加密事件消息示例：

6.提交留言

请求地址：

请求参数示例：

请求参数说明:

响应示例：

响应说明：

7.查询会话记录

请求地址：

请求参数示例：

请求参数说明:

响应示例：

响应说明：

8.文件上传

请求地址：

请求参数示例：

请求参数说明:

响应示例：

响应说明：

事件列表