Skip to main content

文本机器人对接文档

0. 接口鉴权说明

获取token

接口使用OAuth2协议认证,获取token方式参考:认证

使用token

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

GET /chat/v1/robot HTTP/1.1
Host: openapi.icsoc.net
Authorization: {获取到的token}

接口地址

https://openapi.icsoc.net

1.初始化访客接口

请求地址

GET /chat/v1/robot/initClient?robotId=123&clientId=user123

响应示例

{
"code": "200",
"message": "成功",
"data": {
"guideQuestion": {
"beforeWord": "猜你想问",
"afterWord": "点击问题快速获取答案",
"questions": [
{
"question": "热点问题1",
"hits": 12
}
]
},
"topAsks":[
{
"question":"热点问题1",
"hits": 12
}
],
"newAdds":[
{
"question":"新增问题1",
"hits": 12
}
]
}
}

请求参数说明

字段名类型必填说明备注
robotIdstring机器人id机器人列表接口返回的robotId
clientIdstring访客的唯一标识传递自定义的访客标识,每个标识代表一个访客,如果是相同的则代表为同一个访客

响应参数说明

字段名类型说明备注
guideQuestionjson引导问题信息
commonQuestion.beforeWordstring前置说辞
commonQuestion.afterWordstring后置说辞
commonQuestion.questions数组引导问题列表
commonQuestion.questions[0].questionstring引导问题内容
guideQuestions.questions[0].hits数组引导问题命中数
topAsks数组热点问题列表
topAsks[0].questionstring热点问题内容
topAsks[0].questionint热点问题命中数
newAdds数组新增问题列表
newAdds[0].questionstring新增问题内容
newAdds[0].hitsint新增问题命中数

2.问答接口

请求地址:

GET /chat/v1/robot/answer?robotId=123&clientId=user123&question=今天天气怎么样&original=true

响应示例:

serviceType为robot

{
"code": "200",
"message": "成功",
"data": {
"serviceType":"robot",
"robotReply": [
{
"aid": "123456",
"cluid": "xxxxxxx",
"qid": "12347",
"knowledgeId": 123451,
"answerType": 20,
"msgtype": "text",
"text":{
"content": "晴天"
},
"recommendQuestion": {
"list": [
{
"question": "今天星期几"
}
]
}
}
],
"capsules": [
{
"id": 123456,
"name": "天气"
}
]
}
}

serviceType为seat

{
"code": "200",
"message": "成功",
"data": {
"question": "测试客服",
"serviceType": "seat",
"robotReply": [
{
"aid": "326088",
"cluid": "a697ee82ba564a9e92c36b8dcfa08626",
"qid": "12347",
"msgtype": "text",
"answerType": 120,
"revertType": "agent",
"revertObject": "1234",
"text": {
"content": "请稍等,正在为你转接客服"
}
}
]
}
}

请求参数说明

字段名类型必填说明备注
robotIdstring机器人id机器人列表接口返回的robotId
clientIdstring访客的唯一标识
questionstring访客发送的问题需要进行urlencode编码URLEncoder.encode("question", "UTF-8")
originalboolean返回答案是否为原生答案true 返回原生答案(适用于网页); false 返回组装答案(适用于微信渠道)

响应参数说明

字段名类型说明备注
serviceTypestring服务类型robot:机器人答案;seat:转人工类型的答案
robotReply数组机器人匹配到的答案信息匹配度越高,数组排位越靠前
capsules数组引导胶囊列表
capsules[0].idlong引导胶囊id
capsules[0].namestring引导胶囊名称

robotReply字段说明

字段名类型说明备注
aidstring答案ID答案评价时用到(如果为null, 该答案不需要评价)
cluidstring本次聊天的uid答案评价时用到(如果为null, 该答案不需要评价)
qidstring问题ID
knowledgeIdlong知识点ID
answerTypeint答案类型40多轮;80未知答案;120转人工类型;其他值为已知答案
revertTypestring转人工类型agent转座席 queue转技能组
revertObjectstring转人工对象当revertType为agent,revertObject为座席ID;当revertType为queue,revertObject为技能组ID
recommendQuestionjson推荐问题
recommendQuestion.list数组推荐问题列表
recommendQuestion.list[0].questionstring推荐问题内容
msgtypestring消息类型text文本消息;richtext富文本消息;news图文消息;guide反问向导;image图片消息;voice语音消息;video视频消息;document文档消息;file文件消息
textjson文本消息内容当msgtype为不同类型时,消息内容对应的对象如下说明

当msgType为richtext

{
"msgType":"richtext",
"richtext":{
"original": "<a>aaaa</a>",
"description":"aaaa",
"picurl":"http://xxx.png",
"title": "标题",
"url": "http://xxxx.com"
}
}
字段名类型说明备注
richtextjson富文本消息内容
originalstring富文本原生内容
descriptionstring富文本描述description、picurl、title、url联合使用,主要针对微信图文消息
picurlstring图片链接
titlestring富文本消息标题
urlstring点击消息跳转链接

当msgType为image

{
"msgType":"image",
"image":{
"name": "aaaa",
"format":"png",
"url":"http://aaaa.png"
}
}
字段名类型说明备注
imagejson图片消息内容
namestring图片名称
formatstring图片类型
urlstring图片地址

当msgType为voice:

{
"msgType":"voice",
"voice":{
"name": "aaaa",
"format":"mp3",
"url":"http://aaaa.mp3"
}
}
字段名类型说明备注
voicejson语音消息内容
namestring语音名称
formatstring语音类型
urlstring语音地址

当msgType为video:

{
"msgType":"video",
"video":{
"name": "aaaa",
"format":"mp4",
"url":"http://aaaa.mp4"
}
}
字段名类型说明备注
videojson视频消息内容
namestring视频名称
formatstring视频类型
urlstring视频地址

当msgType为document

{
"msgType":"document",
"document":{
"name": "aaaa",
"format":"doc",
"url":"http://aaaa.doc"
}
}
字段名类型说明备注
documentjson文档消息内容
namestring文档名称
formatstring文档类型
urlstring文档地址

当msgType为file

{
"msgType":"file",
"file":{
"name": "aaaa",
"format":"bat",
"url":"http://aaaa.bat"
}
}
字段名类型说明备注
filejson文件消息内容
namestring文件名称
formatstring文件类型
urlstring文件地址

当msgType为news:

{
"msgType":"news",
"news":{
"articles": [
{
"description":"aaaa",
"picurl":"http://xxx.png",
"title": "标题",
"url": "http://xxxx.com"
}
]
}
}
字段名类型说明备注
newsjson图文消息内容
articles数组图文消息集合
descriptionstring图文描述
picurlstring图文链接
titlestring图文消息标题
urlstring点击图文消息跳转链接

当msgType为guide:

{
"msgType":"guide",
"guide":[
{
"beforeWord":"你好,你是否想问:",
"afterWord":"请输入序号回复",
"title": [
{
"question":"1.咨询"
}
]
}
]
}
字段名类型说明备注
guidejson访问向导消息内容
beforeWordstring前置说辞
afterWordstring后置说辞
titlejson向导列表
questionstring向导内容

3.触发引导胶囊接口

请求地址

GET /chat/v1/robot/capsule?robotId=123&clientId=user123&capsuleId=123456&capsuleName=天气&original=true

响应示例:

{
"code": "200",
"message": "成功",
"data": {
"serviceType":"robot",
"robotReply": [
{
"aid": "123456",
"cluid": "xxxxxxx",
"answerType": 20,
"msgtype": "text",
"text":{
"content": "晴天"
},
"recommendQuestion": {
"list": [
{
"question": "今天星期几"
}
]
}
}
],
"capsules": [
{
"id": 456,
"name": "预测"
}
]
}
}

请求参数说明

字段名类型必填说明备注
robotIdstring机器人id机器人列表接口返回的robotId
clientIdstring访客的唯一标识
capsuleIdlong引导胶囊id取问答接口返回的capsules中的id字段
capsuleNamestring引导胶囊名称取问答接口返回的capsules中的name字段
originalboolean返回答案是否为原生答案true 返回原生答案(适用于网页); false 返回组装答案(适用于微信渠道)

响应参数说明

同问答接口响应参数说明

4.faq评价接口

请求地址

GET /chat/v1/robot/evaluate?robotId=123&clientId=user123&aid=123&cluid=xxxaaad&satisfaction=1

响应示例

{
"code": "200",
"message": "成功",
"data":{
"appreciation": "谢谢您的评价,我会继续努力的"
}
}

请求参数说明

字段名类型必填说明约束
robotIdstring机器人id机器人列表接口返回的robotId
clientIdstring访客的唯一标识
aidstring答案ID取问答接口返回的aid字段
cluidstring本次聊天的uid取问答接口返回的cluid字段
satisfactionint满意度评价1满意;2不满意

响应参数说明

字段名类型说明备注
appreciationstring评价感谢语

5.机器人列表

请求地址

POST /chat/v1/robot/api/config/list

请求示例:

{
"name":"ro",
"pageNo":1,
"pageSize":20
}

响应示例:

{
"code":"200",
"message":"成功",
"data":{
"total":0,
"size":20,
"current":0,
"rows":[
{
"id":200,
"vccId":782,
"name":"robot_001",
"nickName":"机器人1号",
"avatar":"",
"robotId":"472",
"remark":"",
"createTime":"2022-09-29 16:14:34",
"updateTime":"2022-09-29 16:14:34",
"updateUser":"朴树 12306"
}
],
"pages":0
}
}

请求参数说明

字段名类型必填说明约束
nameString机器人名称
pageNoInteger第几页
pageSizeInteger每页条数

响应参数说明

字段名类型说明备注
vccIdInteger企业ID
nameString机器人名称
nickNameString昵称
avatarString头像
robotIdString机器人Id
remarkString备注
createTimeDate创建时间
updateTimeDate最近创建时间
updateUserString最近修改人

6.新增机器人

请求地址

POST /chat/v1/robot/api/config/insert

请求示例

{
"name":"test1",
"nickName":"test1",
"remark":"test1",
"avatar":""
}

响应示例

{
"code":"200",
"message":"成功",
"data":123
}

请求参数说明

字段名类型必填说明约束
nameString机器人名称请输入20个字符以内,限制为中文、数字、字母、下划线
nickNameString机器人昵称请输入20个字符以内,限制为中文、数字、字母、下划线
avatarString头像
remarkString备注200字符以内

响应参数说明

字段名类型说明备注
dataInteger新增数据的ID

7.修改机器人

请求地址

POST /chat/v1/robot/api/config/edit

请求示例

{
"nickName":"机器人1号",
"remark":"",
"avatar":"",
"id":200
}

响应示例

{
"code":"200",
"message":"成功",
"data":true
}

请求参数说明

字段名类型必填说明约束
idIntegerid
nickNameString机器人昵称请输入20个字符以内,限制为中文、数字、字母、下划线
avatarString头像
remarkString备注200字符以内

8.删除机器人

请求地址

POST /chat/v1/robot/api/config/delete

请求示例

{
"remark":"我想删!",
"id":201
}

响应示例

{
"code":"200",
"message":"成功",
"data":true
}

请求参数说明

字段名类型必填说明约束
idIntegerid
remarkString删除备注50个字符以内

9.获取知识类型列表

请求地址

GET /chat/v1/robot/api/config/getFaqTypeList

请求示例

响应示例

{
"code": "200",
"message": "成功",
"data": [
{
"id": -1,
"name": "默认分类",
"parentId": 0
},
{
"id": 34381,
"name": "第二级",
"parentId": 34038
},
{
"id": 34038,
"name": "售后",
"parentId": 0
},
{
"id": 34217,
"name": "极简操作视频",
"parentId": 0
}
]
}

返回参数说明

字段名类型说明备注
idInteger类型ID
nameString类型名称
parentIdInteger父级ID0表示第一级

10.获取知识列表

请求地址

POST /chat/v1/robot/api/config/getKnowledgeList

请求示例

{
"pageNum":1,
"pageSize":20,
"data":{
"classesId":34038,
"content":""
}
}

响应示例

{
"code": "200",
"message": "成功",
"data": {
"total": 45,
"list": [
{
"question": "短信打开失败",
"knowledgeId": 301554,
"createTime": "2022-07-14 10:49:14",
"createUserName": "张田林_2000090"
}
],
"pageNum": 1,
"pageSize": 20,
"pages": 3
}
}

请求参数说明

字段名类型必填说明约束
pageNumInteger第几页
pageSizeInteger每页大小
classesIdInteger类型ID取知识类型列表的id
contentString问题名称

返回参数说明

字段名类型说明备注
questionString问题名称
knowledgeIdInteger知识点ID
createTimeDate创建时间
createUserNameString创建人

11.修改机器人配置

包括修改未知问题说辞、欢迎语推荐、未知问题推荐等

请求地址

POST /chat/v1/robot/api/config/editInfo

请求示例

{
"id": 200,
"welcomeFlag": 1,
"unknownFlag": 1,
"recommendList": {
"preposition": "猜您想问",
"postscript": "点击问题快速获取答案",
"questionList": [
{
"questionType": 2,
"knowledgeId": 302124,
"name": "购物基本流程?"
}
]
},
"guideList": {
"preposition": "猜您想问",
"postscript": "点击问题快速获取答案",
"questionList": [
{
"questionType": 2,
"knowledgeId": 302124,
"name": "购物基本流程?"
},
{
"questionType": 1,
"knowledgeId": "",
"name": ""
}
]
},
"unknownList": [
"不好意思,我不是很理解您的问题,请用一句话准确描述"
]
}

响应示例

{"code":"200","message":"成功","data":true}

请求参数说明

字段名类型必填说明约束
welcomeFlagInteger欢迎语问题推荐开关:1.开 0.关
recommendList.prepositionString前置说辞
recommendList.postscriptString后置说辞
recommendList.questionList[0].questionTypeInteger问题类型:1.智能推荐 2.手机动选择
recommendList.questionList[0].knowledgeIdInteger知识ID
recommendList.questionList[0].nameInteger知识名称
unknownFlagInteger未知问题推荐开关:1.开 0.关
guideList.prepositionString前置说辞
guideList.postscriptString后置说辞
guideList.questionList[0].questionTypeInteger问题类型:1.智能推荐 2.手机动选择
guideList.questionList[0].knowledgeIdInteger知识ID
guideList.questionList[0].nameInteger知识名称
unknownList数组未知问题说辞最多5个

11.机器人详情

请求地址

GET /chat/v1/robot/api/config/detail

请求示例

/chat/v1/robot/api/config/detail?id=200

/chat/v1/robot/api/config/detail?robotId=472

响应示例

{
"code": "200",
"message": "成功",
"data": {
"id": 200,
"vccId": 782,
"name": "robot_001",
"nickName": "机器人1号",
"avatar": "",
"robotId": "472",
"remark": "",
"robotDetailConfig": {
"welcomeFlag": 1,
"recommendList": {
"preposition": "猜您想问",
"postscript": "点击问题快速获取答案",
"questionList": [
{
"questionType": 2,
"knowledgeId": 302124,
"name": "购物基本流程?"
}
]
},
"unknownFlag": 1,
"guideList": {
"preposition": "猜您想问",
"postscript": "点击问题快速获取答案",
"questionList": [
{
"questionType": 2,
"knowledgeId": 302124,
"name": "购物基本流程?"
}
]
},
"unknownList": [
"不好意思,我不是很理解您的问题,请用一句话准确描述"
]
}
}
}

返回参数说明

参数为id或者robotId,二者传其一

返回参数说明

字段名类型必填备注
vccIdInteger企业ID
nameString机器人名称
nickNameString昵称
avatarString头像
robotIdString机器人Id
remarkString备注
robotDetailConfig.welcomeFlagInteger欢迎语问题推荐开关:1.开 0.关
robotDetailConfig.recommendList.prepositionString前置说辞
robotDetailConfig.recommendList.postscriptString后置说辞
robotDetailConfig.recommendList.questionList[0].questionTypeInteger问题类型:1.智能推荐 2.手机动选择
robotDetailConfig.recommendList.questionList[0].knowledgeIdInteger知识ID
robotDetailConfig.recommendList.questionList[0].nameInteger知识名称
robotDetailConfig.unknownFlagInteger未知问题推荐开关:1.开 0.关
robotDetailConfig.guideList.prepositionString前置说辞
robotDetailConfig.guideList.postscriptString后置说辞
robotDetailConfig.guideList.questionList[0].questionTypeInteger问题类型:1.智能推荐 2.手机动选择
robotDetailConfig.guideList.questionList[0].knowledgeIdInteger知识ID
robotDetailConfig.guideList.questionList[0].nameInteger知识名称
robotDetailConfig.unknownList数组未知问题说辞

12.访客侧输入联想

请求地址

GET /chat/v1/robot/inputGuide

请求示例

/chat/v1/robot/inputGuide?robotId=193&clientId=xxxxx&question=测试

响应示例

{
"code": "200",
"message": "成功",
"data": [
{
"content": "其他测试",
"showContent": "其他<span class=\"high-light\">测试</span>"
},
{
"content": "换行测试",
"showContent": "换行<span class=\"high-light\">测试</span>"
},
{
"content": "测试1234",
"showContent": "<span class=\"high-light\">测试</span>1234"
},
{
"content": "测试客服",
"showContent": "<span class=\"high-light\">测试</span>客服"
},
{
"content": "音频测试",
"showContent": "音频<span class=\"high-light\">测试</span>"
}
]
}

请求参数说明

字段名类型必填说明备注
robotIdstring机器人id机器人列表接口返回的robotId
clientIdstring访客的唯一标识
questionstring访客发送的问题需要进行urlencode编码URLEncoder.encode("question", "UTF-8")

响应参数说明

字段名类型说明备注
contentstring联想内容
showContentstring内容中突出显示的内容