文本机器人对接文档

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

请求参数说明

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

响应参数说明

字段名	类型	说明
guideQuestion	json	引导问题信息
commonQuestion.beforeWord	string	前置说辞
commonQuestion.afterWord	string	后置说辞
commonQuestion.questions	数组	引导问题列表
commonQuestion.questions[0].question	string	引导问题内容
guideQuestions.questions[0].hits	数组	引导问题命中数
topAsks	数组	热点问题列表
topAsks[0].question	string	热点问题内容
topAsks[0].question	int	热点问题命中数
newAdds	数组	新增问题列表
newAdds[0].question	string	新增问题内容
newAdds[0].hits	int	新增问题命中数

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": "请稍等，正在为你转接客服"
        }
      }
    ]
  }
}

请求参数说明

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

响应参数说明

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

robotReply字段说明

字段名	类型	说明	备注
aid	string	答案ID	答案评价时用到（如果为null, 该答案不需要评价）
cluid	string	本次聊天的uid	答案评价时用到（如果为null, 该答案不需要评价）
qid	string	问题ID
knowledgeId	long	知识点ID
answerType	int	答案类型	40多轮；60寒暄回复；80未知答案；120转人工类型；其他值为已知答案
revertType	string	转人工类型	agent转座席 queue转技能组
revertObject	string	转人工对象	当revertType为agent,revertObject为座席ID;当revertType为queue,revertObject为技能组ID
recommendQuestion	json	推荐问题
recommendQuestion.list	数组	推荐问题列表
recommendQuestion.list[0].question	string	推荐问题内容
msgtype	string	消息类型	text文本消息；richtext富文本消息；news图文消息；guide反问向导；image图片消息；voice语音消息；video视频消息；document文档消息；file文件消息
text	json	文本消息内容	当msgtype为不同类型时，消息内容对应的对象如下说明

当msgType为richtext

{
  "msgType":"richtext",
  "richtext":{
    "original": "<a>aaaa</a>",
    "description":"aaaa",
    "picurl":"http://xxx.png",
    "title": "标题",
    "url": "http://xxxx.com"
  }
}

字段名	类型	说明	备注
richtext	json	富文本消息内容
original	string	富文本原生内容
description	string	富文本描述	description、picurl、title、url联合使用，主要针对微信图文消息
picurl	string	图片链接
title	string	富文本消息标题
url	string	点击消息跳转链接

当msgType为image

{
  "msgType":"image",
  "image":{
    "name": "aaaa",
    "format":"png",
    "url":"http://aaaa.png"
  }
}

字段名	类型	说明
image	json	图片消息内容
name	string	图片名称
format	string	图片类型
url	string	图片地址

当msgType为voice:

{
  "msgType":"voice",
  "voice":{
    "name": "aaaa",
    "format":"mp3",
    "url":"http://aaaa.mp3"
  }
}

字段名	类型	说明
voice	json	语音消息内容
name	string	语音名称
format	string	语音类型
url	string	语音地址

当msgType为video:

{
  "msgType":"video",
  "video":{
    "name": "aaaa",
    "format":"mp4",
    "url":"http://aaaa.mp4"
  }
}

字段名	类型	说明
video	json	视频消息内容
name	string	视频名称
format	string	视频类型
url	string	视频地址

当msgType为document

{
  "msgType":"document",
  "document":{
    "name": "aaaa",
    "format":"doc",
    "url":"http://aaaa.doc"
  }
}

字段名	类型	说明
document	json	文档消息内容
name	string	文档名称
format	string	文档类型
url	string	文档地址

当msgType为file

{
  "msgType":"file",
  "file":{
    "name": "aaaa",
    "format":"bat",
    "url":"http://aaaa.bat"
  }
}

字段名	类型	说明
file	json	文件消息内容
name	string	文件名称
format	string	文件类型
url	string	文件地址

当msgType为news:

{
  "msgType":"news",
  "news":{
    "articles": [
      {
        "description":"aaaa",
        "picurl":"http://xxx.png", 
        "title": "标题",
        "url": "http://xxxx.com"
      }
    ]
  }
}

字段名	类型	说明
news	json	图文消息内容
articles	数组	图文消息集合
description	string	图文描述
picurl	string	图文链接
title	string	图文消息标题
url	string	点击图文消息跳转链接

当msgType为guide:

{
  "msgType":"guide",
  "guide":[
    {
      "beforeWord":"你好，你是否想问：",
      "afterWord":"请输入序号回复",
      "title": [
        {
          "question":"1.咨询"
        }
      ]
    }
  ]
}

字段名	类型	说明
guide	json	访问向导消息内容
beforeWord	string	前置说辞
afterWord	string	后置说辞
title	json	向导列表
question	string	向导内容

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": "预测"
      }
    ]
  }
}

请求参数说明

字段名	类型	必填	说明	备注
robotId	string	是	机器人id	机器人列表接口返回的robotId
clientId	string	是	访客的唯一标识
capsuleId	long	是	引导胶囊id	取问答接口返回的capsules中的id字段
capsuleName	string	是	引导胶囊名称	取问答接口返回的capsules中的name字段
original	boolean	是	返回答案是否为原生答案	true 返回原生答案（适用于网页）; false 返回组装答案（适用于微信渠道）

响应参数说明

同问答接口响应参数说明

4.faq评价接口

请求地址

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

响应示例

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

请求参数说明

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

响应参数说明

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

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

请求参数说明

字段名	类型	必填	说明
name	String	否	机器人名称
pageNo	Integer	是	第几页
pageSize	Integer	是	每页条数

响应参数说明

字段名	类型	说明
vccId	Integer	企业ID
name	String	机器人名称
nickName	String	昵称
avatar	String	头像
robotId	String	机器人Id
remark	String	备注
createTime	Date	创建时间
updateTime	Date	最近创建时间
updateUser	String	最近修改人

6.新增机器人

请求地址

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

请求示例

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

响应示例

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

请求参数说明

字段名	类型	必填	说明	约束
name	String	是	机器人名称	请输入20个字符以内，限制为中文、数字、字母、下划线
nickName	String	是	机器人昵称	请输入20个字符以内，限制为中文、数字、字母、下划线
avatar	String	否	头像
remark	String	否	备注	200字符以内

响应参数说明

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

7.修改机器人

请求地址

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

请求示例

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

响应示例

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

请求参数说明

字段名	类型	必填	说明	约束
id	Integer	是	id
nickName	String	是	机器人昵称	请输入20个字符以内，限制为中文、数字、字母、下划线
avatar	String	否	头像
remark	String	否	备注	200字符以内

8.删除机器人

请求地址

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

请求示例

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

响应示例

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

请求参数说明

字段名	类型	必填	说明	约束
id	Integer	是	id
remark	String	否	删除备注	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
    }
  ]
}

返回参数说明

字段名	类型	说明	备注
id	Integer	类型ID
name	String	类型名称
parentId	Integer	父级ID	0表示第一级

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

请求参数说明

字段名	类型	必填	说明	约束
pageNum	Integer	是	第几页
pageSize	Integer	是	每页大小
classesId	Integer	否	类型ID	取知识类型列表的id
content	String	否	问题名称

返回参数说明

字段名	类型	说明
question	String	问题名称
knowledgeId	Integer	知识点ID
createTime	Date	创建时间
createUserName	String	创建人

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}

请求参数说明

字段名	类型	必填	说明	约束
welcomeFlag	Integer	是	欢迎语问题推荐开关：1.开 0.关
recommendList.preposition	String	是	前置说辞
recommendList.postscript	String	是	后置说辞
recommendList.questionList[0].questionType	Integer	是	问题类型：1.智能推荐 2.手机动选择
recommendList.questionList[0].knowledgeId	Integer	是	知识ID
recommendList.questionList[0].name	Integer	是	知识名称
unknownFlag	Integer	是	未知问题推荐开关：1.开 0.关
guideList.preposition	String	是	前置说辞
guideList.postscript	String	是	后置说辞
guideList.questionList[0].questionType	Integer	是	问题类型：1.智能推荐 2.手机动选择
guideList.questionList[0].knowledgeId	Integer	是	知识ID
guideList.questionList[0].name	Integer	是	知识名称
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,二者传其一

返回参数说明

字段名	类型	必填	备注
vccId	Integer	企业ID
name	String	机器人名称
nickName	String	昵称
avatar	String	头像
robotId	String	机器人Id
remark	String	备注
robotDetailConfig.welcomeFlag	Integer	是	欢迎语问题推荐开关：1.开 0.关
robotDetailConfig.recommendList.preposition	String	是	前置说辞
robotDetailConfig.recommendList.postscript	String	是	后置说辞
robotDetailConfig.recommendList.questionList[0].questionType	Integer	是	问题类型：1.智能推荐 2.手机动选择
robotDetailConfig.recommendList.questionList[0].knowledgeId	Integer	是	知识ID
robotDetailConfig.recommendList.questionList[0].name	Integer	是	知识名称
robotDetailConfig.unknownFlag	Integer	是	未知问题推荐开关：1.开 0.关
robotDetailConfig.guideList.preposition	String	是	前置说辞
robotDetailConfig.guideList.postscript	String	是	后置说辞
robotDetailConfig.guideList.questionList[0].questionType	Integer	是	问题类型：1.智能推荐 2.手机动选择
robotDetailConfig.guideList.questionList[0].knowledgeId	Integer	是	知识ID
robotDetailConfig.guideList.questionList[0].name	Integer	是	知识名称
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>"
    }
  ]
}

请求参数说明

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

响应参数说明

字段名	类型	说明	备注
content	string	联想内容
showContent	string	内容中突出显示的内容

0. 接口鉴权说明​

获取token​

使用token​

接口地址​

1.初始化访客接口​

请求地址​

响应示例​

请求参数说明​

响应参数说明​

2.问答接口​

请求地址：​

响应示例：​

serviceType为robot​

serviceType为seat​

请求参数说明​

响应参数说明​

robotReply字段说明​

当msgType为richtext​

当msgType为image​

当msgType为voice:​

当msgType为video:​

当msgType为document​

当msgType为file​

当msgType为news:​

当msgType为guide:​

3.触发引导胶囊接口​

请求地址​

响应示例：​

请求参数说明​

响应参数说明​

4.faq评价接口​

请求地址​

响应示例​

请求参数说明​

响应参数说明​

5.机器人列表​

请求地址​

请求示例：​

响应示例：​

请求参数说明​

响应参数说明​

6.新增机器人​

请求地址​

请求示例​

响应示例​

请求参数说明​

响应参数说明​

7.修改机器人​

请求地址​

请求示例​

响应示例​

请求参数说明​

8.删除机器人​

请求地址​

请求示例​

响应示例​

请求参数说明​

9.获取知识类型列表​

请求地址​

请求示例​

响应示例​

返回参数说明​

10.获取知识列表​

请求地址​

请求示例​

响应示例​

请求参数说明​

返回参数说明​

11.修改机器人配置​

请求地址​

请求示例​

响应示例​

请求参数说明​

11.机器人详情​

请求地址​

请求示例​

响应示例​

返回参数说明​

返回参数说明​

12.访客侧输入联想​

0. 接口鉴权说明

获取token

使用token

接口地址

1.初始化访客接口

请求地址

响应示例

请求参数说明

响应参数说明

2.问答接口

请求地址：

响应示例：

serviceType为robot

serviceType为seat

请求参数说明

响应参数说明

robotReply字段说明

当msgType为richtext

当msgType为image

当msgType为voice:

当msgType为video:

当msgType为document

当msgType为file

当msgType为news:

当msgType为guide:

3.触发引导胶囊接口

请求地址

响应示例：

请求参数说明

响应参数说明

4.faq评价接口

请求地址

响应示例

请求参数说明

响应参数说明

5.机器人列表

请求地址

请求示例：

响应示例：

请求参数说明

响应参数说明

6.新增机器人

请求地址

请求示例

响应示例

请求参数说明

响应参数说明

7.修改机器人

请求地址

请求示例

响应示例

请求参数说明

8.删除机器人

请求地址

请求示例

响应示例

请求参数说明

9.获取知识类型列表

请求地址

请求示例

响应示例

返回参数说明

10.获取知识列表

请求地址

请求示例

响应示例

请求参数说明

返回参数说明

11.修改机器人配置

请求地址

请求示例

响应示例

请求参数说明

11.机器人详情

请求地址

请求示例

响应示例

返回参数说明

返回参数说明

12.访客侧输入联想