openAPI 接入文档
接口鉴限说明
获取token
openAPI相关接口使用OAuth2协议认证,获取token方式参考:如何认证
使用token
调用接口时需要在header中设置Authorization。
示例:
POST https://openapi.icsoc.net/chat/v1/message/init_session
Authorization: Bearer f763deae8eb9eca2e507f7463340f66381c0d21c
接口列表
1.创建会话
请求地址:
请求参数示例:
{
"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.发送消息
请求地址:
请求接口如果返回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.查询评价配置
请求地址:
请求参数示例:
?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.提交评价
请求地址:
请求参数示例:
{
"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条消息记录。
请求地址:
POST 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 | 会话结束通知用户 |