初始化会话

请求地址

• POST /v1/initClient

请求参数

Request fields

Path	Type	Optional	Description
robotId	Integer	false	机器人id:此次会话对应的机器人的标识id.
channelId	Integer	false	场景id：此次会话对应的场景标识id.
modelKey	String	true	常见问题模板ID，在’km-机器人-知识库管理-推荐-ID’查看.
accessKeyId	String	true	对接设置的应用的应用ID，对应获取应用的appID字段，在’km-管理-应用管理-应用ID’查看.
platform	Integer	true	渠道: 0:web, 1:普通微信, 2:安卓, 3:ios, 4:微博, 5:客服系统API, 6:多商户, 7:微信小程序, 8:企业微信
customer	Map	true	客户信息.
shortcutCustomId	String	true	快捷入口自定义ID.

customer对应的结构

{
    "id": "客户ID（Long类型）",
    "nickname": "客户名称",
    "ip": "客户IP",
    "province": "IP所在省",
    "city": "IP所在市",
    "orgName": "公司名称",
    "email": "客户邮箱",
    "phone": "客户电话",
    "tags": "客户标签",
    "desc": "描述",
    "level": "客户等级",
    "platform": "渠道",
    "src": "来源",
    "srcUrl": "来源URL",
    "webPluginName": "来源插件",
    "keyword": "搜索关键词",
    "generatedChannel": "自定义渠道信息",
    "loginUrl": "访问着陆页",
    "sessionUrl": "对话发起页",
    "weChatOpenId": "微信OPENID",
    "customer_token": "客户外部ID",
    "customField": "自定义字段Map<String,String>",
    "c_cf_dialogueDesc": "对话描述（使用方式参考webhook任务推送型接口）"

}

请求结果

Path	Type	Description
code	Integer	状态码
message	String	返回信息
visible	Boolean
data	Object	返回数据

data

Path	Type	Description
sessionId	Integer	会话id.
logId	Integer	机器人返回的id.
welcomeMessage	String	欢迎语.
leadingWord	String	引导语.
commonQuestionModel	Object	常见问题.

commonQuestionModel

Path	Type	Description
id	Integer	id.
robotId	Integer	机器人id.
name	String	模板名称.
channelId	Integer	场景id.
description	String	描述.
modelKey	String	常见问题模板ID，在’km-机器人-知识库管理-推荐-ID’查看.
commonQuestionCategoryList	Array	常见问题分类（里面包含分类下常见问题列表）.
shortcutEntryList	Array	快捷入口列表.

commonQuestionCategoryList

Path	Type	Description
id	Integer	分类id.
modelId	Integer	常见问题模板id.
name	String	目录名.
sorts	Integer	预留排序字段.
questionList	Array	分类下常见问题列表.

questionList

Path	Type	Description
id	Integer	问题的标识id.
content	String	问题的内容.
type	Integer	类型 1：普通问题 4：闲聊问题.
answer	Object	答案.
answer.content	String	答案内容
answer.type	Integer	答案类型
answer.id	Integer	答案ID

shortcutEntryList

Path	Type	Description
modelId	Integer	快捷入口列表id.
type	Integer	类型:1-文本,2-链接.
name	String	入口名称.
content	String	内容.
pic	String	图片url.
sorts	Integer	预留排序字段.
isDefault	Integer	是否默认.

示例

$ curl 'https://km.udesk.cn/api/v1/initClient?email=admin@udesk.cn&timestamp=1529402445&sign=fbe02e2b9f76179da49ea619cbabdde909b73a2f' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 103,
  "channelId" : 106,
  "modelKey" : "0",
  "accessKeyId" : "/+7772AKE6kv8AVNjWqP",
  "platform" : 5,
  "customer" : null
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "sessionId": 451724,
        "logId": 793020,
        "welcomeMessage": "你好，很高兴为您服务！",
        "leadingWord": "常见问题",
        "commonQuestionList": [],
        "commonQuestionModel": {
            "id": 108,
            "name": "默认常见问题",
            "description": "常见问题",
            "commonQuestionCategoryList": [
                {
                    "id": 76,
                    "modelId": 108,
                    "name": "111",
                    "questionList": [
                        {
                            "id": 8645,
                            "content": "社保怎么办理主引导选择啊",
                            "type": 1,
                            "answer": {
                                "content": "<p>打电话12345</p>",
                                "type": 2,
                                "id": 4436
                            }
                        },
                        {
                            "id": 8647,
                            "content": "社保如何办理",
                            "type": 1,
                            "answer": {
                                "content": "<p>网上查询</p>",
                                "type": 2,
                                "id": 4437
                            }
                        }
                    ]
                }
            ]
        }
    }
}

点击流程接口

请求地址

• POST /v1/flow

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	会话id：此次会话的标识id，在初始化会话（/api/initClient）返回时获取.
logId	Integer	true	流程点击所在的log的标识id，在机器人返回时提供.
flowId	Integer	true	流程标识id，在机器人返回流程内容（flowContent）中提供.
flowContent	String	true	流程具体内容.

请求结果

Path	Type	Description
code	Integer	执行结果码
message	String	执行结果说明
data	Object	会话信息
data.sessionId	Integer	会话id.
data.logId	Integer	机器人返回的log的标识id.
data.flowId	Integer	流程id,返回流程时有效.
data.flowTitle	String	流程标题，返回流程时有效.
data.flowContent	String	流程内容，返回流程时有效.内容中只有带有data-type和data-id属性的html元素是可点击的，并且所有的data-*属性的值都是String类型的
data.restrictionState	Object	交互量限制状态.
data.restrictionState.exceededFlag	Integer	超限标识【0正常/1已超限】
data.restrictionState.usedCount	Integer	已使用数量
data.restrictionState.totalCount	Integer	限制总量

示例

$ curl 'https://km.udesk.cn/api/v1/flow?email=admin@udesk.cn&timestamp=1529402444&sign=17dfc106671e1cd2442ba6e61c778aac86bb3035' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450285,
  "logId" : 785709,
  "flowId" : 42,
  "flowContent" : "<p>11111</p><p>22222</p><p>33333</p>"
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "data": {
        "sessionId": 28905,
        "logId": 793020,
        "flowId": 285,
        "flowTitle": "流程问题",
        "flowContent": "<p>1111</p>",
        "suggestQuestionList": [],
        "restrictionState": {
            "exceededFlag": 0,
            "usedCount": 32,
            "totalCount": 1000000
        }
    }
}

请求失败原因

{
  "code": 400,
  "message": "{具体的异常信息}",
  "visible": false
}

message	description
"sessionId does not exist! Please reinitialize"	对应sessionId的对话不存在
"【...】javax.validation.constraints.NotNull.message"	【具体字段】不能为空
"The system could not find the process"	对应flowId的流程不存在

点击问题行为接口

请求地址

• POST /v1/hit

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	此次会话的标识id.
queryType	Integer	true	用户点击类型 枚举 6:常见问题点击 7:建议问题点击 8:流程中的问题点击 9:智能提示点击.
logId	Integer	true	用户点击行为所在log的标识id（当queryType为9时，该字段不填）.
questionId	Integer	true	问题id（点击问题的id）.
questionContent	String	true	问题内容（点击问题的内容）.
contentType	String	true	枚举：text ,rich 如果是text，会把ansContent富文本转换成普通文本
hitSource	Integer	true	1.快捷入口的消息，2.按钮文案的点击，3.商品列表结构化消息.

请求结果

Path	Type	Description
code	Integer	执行结果码
message	String	执行结果说明
data	Object	会话信息
data.sessionId	Integer	会话id.
data.logId	Integer	机器人返回的log的标识id.
data.ansContent	Var	返回对应的答案的内容.
data.ansType	Integer	答案类型
data.attachmentList	Array	问题的附件列表
data.attachmentList[].name	String	问题附件的名称
data.attachmentList[].address	String	问题附件的链接
data.attachmentList[].size	Integer	问题附件的大小
data.flowId	Integer	流程id,返回流程时有效.
data.flowTitle	String	流程标题，返回流程时有效.
data.flowContent	String	流程内容，返回流程时有效.内容中只有带有data-type和data-id属性的html元素是可点击的，并且所有的data-*属性的值都是String类型的
data.hitQuestion	String	返回召回的问题.
data.msgType	String	答案的类型.
data.switchStaffType	Integer	1.推荐转人工 2.满足条件转人工 3.发送消息.
data.switchStaffAnswer	String	转人工消息.
data.suggestQuestionList	Array	建议问题列表.
data.suggestQuestionList[].id	Integer	建议问题的标识id.
data.suggestQuestionList[].content	String	建议问题的内容.
data.suggestQuestionList[].type	Integer	建议问题的类型
data.suggestQuestionList[].answer	Object	建议问题的答案.
data.suggestQuestionList[].answer.content	String	建议问题的答案内容
data.suggestQuestionList[].answer.type	Integer	建议问题的答案类型
data.suggestQuestionList[].answer.id	Integer	建议问题的答案ID
data.aid	Integer	返回对应的答案的id,返回答案时有效

示例

$ curl 'https://km.udesk.cn/api/v1/hit?email=admin@udesk.cn&timestamp=1529402439&sign=2c8f96911159fae72a493365a9692ce66c5c2b5d' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450283,
  "queryType" : 7,
  "logId" : 785703,
  "questionId" : 232,
  "questionContent" : "谁的风扇"
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "sessionId": 451727,
        "logId": 793031,
        "ansContent": "<p>不和平</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
        "attachmentList": [],
        "suggestQuestionList": [
            {
                "id": 8657,
                "content": "世界哪里和平了",
                "type": 1,
                "answer": {
                    "content": "<p>没有</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
                    "type": 2,
                    "id": 4442,
                    "deleteFlag": 0
                }
            },
            {
                "id": 9259,
                "content": "你想去哪儿",
                "type": 1,
                "answer": {
                    "content": "<p>北海</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
                    "type": 2,
                    "id": 5009,
                    "deleteFlag": 0
                }
            }
        ],
        "aid": 4441
    }
}

请求失败原因

{
  "code": 400,
  "message": "{具体的异常信息}",
  "visible": false
}

message	description
"sessionId does not exist! Please reinitialize"	对应sessionId的对话不存在
"【...】javax.validation.constraints.NotNull.message"	【具体字段】不能为空

获取会话窗口-常见问题列表

请求地址

• POST /v1/chat/commonQuestions

请求参数

Request fields

Path	Type	Optional	Description
robotId	Integer	false	机器人id.
channelId	Integer	false	场景ID.
modelKey	String	false	常见问题模板ID，在’km-机器人-知识库管理-常见问题-ID’查看.

请求结果

Path	Type	Description
code	Integer	执行结果码
message	String	执行结果说明
data	Array	常见问题列表信息
data[].id	Integer	常见问题列表的分类id.
data[].modelId	Integer	常见问题列表的模板id.
data[].name	String	常见问题列表的分类名称.
data[].questionList	Array	分类下常见问题.
data[].questionList[].id	Integer	问题id.
data[].questionList[].content	String	问题的内容,type=5时表示消息的内容
data[].questionList[].type	Integer	类型 1:普通问题 4:闲聊问题 5:消息
data[].questionList[].answer	Object	答案.
data[].questionList[].answer.content	String	答案内容
data[].questionList[].answer.type	Integer	答案类型
data[].questionList[].answer.id	Integer	答案ID

示例

$ curl 'https://km.udesk.cn/api/v1/chat/commonQuestions?email=admin@udesk.cn&timestamp=1529569037&sign=4bc33f53e473d6db70e900fb07b947a9ee18f905' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 112,
  "channelId" : 118,
  "modelKey" : "aaa"
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": {
        "pageNum": 1,
        "pageSize": 1,
        "total": 1
    },
    "data": [
        {
            "id": 76,
            "modelId": 108,
            "name": "111",
            "questionList": [
                {
                    "id": 8645,
                    "content": "社保怎么办理主引导选择啊",
                    "type": 1,
                    "answer": {
                        "content": "<p>打电话12345</p>",
                        "type": 2,
                        "id": 4436
                    }
                },
                {
                    "id": 8647,
                    "content": "社保如何办理",
                    "type": 1,
                    "answer": {
                        "content": "<p>网上查询</p>",
                        "type": 2,
                        "id": 4437
                    }
                }
            ]
        }
    ]
}

获取会话窗口-热点问题列表

请求地址

• POST /v1/chat/hotQuestions

请求参数

Request fields

Path	Type	Optional	Description
limitDayNum	Integer	false	最近多少天（不超过100）.
limitResultNum	Integer	false	最多返回多少记录（不超过50）.
robotId	Integer	false	机器人ID

请求结果

Path	Type	Description
code	Integer	执行结果码
message	String	执行结果说明
data	Array	问题列表
data[].id	Integer	问题的标识id.
data[].content	String	问题的内容.
data[].type	Integer	问题类型
data[].answer	Object	答案.
data[].answer.content	String	答案内容
data[].answer.type	Integer	答案类型
data[].answer.id	Integer	答案ID
data[].matchCount	Integer	匹配数量.

示例

$ curl 'https://km.udesk.cn/api/v1/chat/hotQuestions?email=admin@udesk.cn&timestamp=1529569036&sign=27bfe3f1ece19e13b03ff669d30830322ae4cfa3' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "limitDayNum" : 100,
  "limitResultNum" : 2,
  "robotId" : 83
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": {
        "pageNum": 1,
        "pageSize": 2,
        "total": 2
    },
    "data": [
        {
            "id": 844,
            "content": "你是谁？",
            "type": 1,
            "answer": {
                "content": "我是robot机器人啊",
                "type": 2,
                "id": 552
            },
            "matchCount": 24
        },
        {
            "id": 9426,
            "content": "谁的范德萨分",
            "type": 3,
            "answer": {
                "content": "123",
                "type": 1,
                "id": 5124
            },
            "matchCount": 13
        }
    ]
}

评价机器人返回的答案

请求地址

• POST /v1/surveyQuestion

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	会话Id.
questionSurveyOptionId	Integer	false	评价选项 1：满意 2：不满意.
logId	Integer	true	被评价答案所在记录的Id,在机器人返回中获取.

请求结果

Path	Type	Description
code	Integer	执行状态码
message	String	执行结果说明

示例

$ curl 'https://km.udesk.cn/api/v1/surveyQuestion?email=admin%40udesk.cn&timestamp=1529402453&sign=de8f53541749eb530fc006941d6af1af4e917067' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450289,
  "questionSurveyOptionId" : 1,
  "logId" : 785716
}'

返回

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}

请求失败原因

{
  "code": 400,
  "message": "{具体的异常信息}",
  "visible": false
}

message	description
This reply has been evaluated!	对话已评价
The relationship between sessionId and sessionLogId does not exist!	logid不属于对应sessionid的对话
sessionId does not exist! Please reinitialize	对应sessionId的对话不存在
【...】javax.validation.constraints.NotNull.message	【具体字段】不能为空

评价机器人会话

请求地址

• POST /v1/surveySession

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	会话id.
sessionSurveyOptionId	Integer	true	评价选项 1：未评价 2：满意 3：一般 4：不满意.
surveyContent	String	true	评价内容.

请求结果

Path	Type	Description
code	Integer	执行状态码
message	String	执行结果信息
data	Object	返回内容
data.switchStaffType	Integer	1.微信渠道显示引导语 2.满足条件转人工.
data.switchStaffTips	String	转人工提示.

示例

$ curl 'https://km.udesk.cn/api/v1/surveySession?email=admin@udesk.cn&timestamp=1529402455&sign=d4be213127c62bb5b53dea5f5e52eaad06b2362f' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450290,
  "sessionSurveyOptionId" : 4,
  "surveyContent" : "hehe"
}'

返回

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}

普通对话

请求地址

• POST /v1/chat

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	会话id：此次会话的标识id，在初始化会话（/api/initClient）时获取.
robotId	Integer	false	机器人id:此次会话对应的机器人标识id.
queryContent	String	false	用户问话内容.
channel_id	Integer	true	知识库场景ID
weixin_openid	String	true	微信的openid
contentType	String	true	文本类型 如果值为"text"，会把ansContent富文本转换成普通文本
chatMode	Integer	true	会话模式 1.智能模式 2.任务式会话 3.FAQ 4.资料库

请求结果

Path	Type	Description
code	Integer	执行状态码
message	String	执行结果说明
data	Object	对话信息
data.sessionId	Integer	会话id.
data.logId	Integer	机器人返回的log的标识id.
data.enableAppraise	Boolean	对话是否允许评价
data.ansContent	String	返回对应的答案的内容.
data.ansType	Integer	返回答案类型
data.msgbox	String	语音类型(data.ansType="audio")时,同时返回的文案
data.flowId	Integer	流程id,返回流程时有效.
data.flowTitle	String	流程标题，返回流程时有效.
data.flowContent	String	流程内容，返回流程时有效.
data.hitQuestion	String	返回召回的问题，.
data.msgType	String	答案的文本类型.
data.switchStaffType	Integer	1.推荐转人工 2.满足条件转人工 3.发送消息.
data.switchStaffAnswer	String	转人消息.
data.suggestQuestionList	Array	建议列表.
data.suggestQuestionList[].id	Integer	建议问题的标识id.
data.suggestQuestionList[].content	String	建议问题的内容.
data.suggestQuestionList[].type	Integer	建议问题类型
data.suggestQuestionList[].answer	Object	建议问题的答案.
data.suggestQuestionList[].answer.content	String	建议问题的答案内容
data.suggestQuestionList[].answer.type	Integer	建议问题的答案类型
data.suggestQuestionList[].answer.questionId	Integer	建议问题的答案对应的问题ID
data.suggestQuestionList[].answer.id	Integer	建议问题的答案ID
data.restrictionState	Object	交互量限制状态.
data.restrictionState.exceededFlag	Integer	超限标识【0正常/1已超限】
data.restrictionState.usedCount	Integer	已使用数量
data.restrictionState.totalCount	Integer	限制总量
data.aid	Integer	返回对应的答案的id.
data.taskChatReturnCommands	Array	任务式对话返回指令集.
data.attachmentList	Array	FAQ问题的附件列表.
data.attachmentList[].name	String	附件名称
data.attachmentList[].address	String	附件地址
data.attachmentList[].size	Integer	附件大小
data.customerServiceId	String	转接客服/客服组的id.
data.customerServiceStatus	Integer	0为客服，1为客服组.
data.multipleMessageFlag	Integer	0否，1是.
data.multipleMessage	Array	多消息.
data.multipleMessage[].messageType	Integer	等同于上文msgType.
data.multipleMessage[].message	Integer	消息内容.
data.multipleMessage[].	Integer	返回对应的答案的id.
data.multipleMessage[]	Integer	返回对应的答案的id.
data.multipleMessage[]	Integer	返回对应的答案的id.

data.msgType对应的data.ansContent结构

枚举值	说明	结构
rich	富文本	带标签的String
selective_list	选择列表	ans_selective_list
show_product	展示商品	ans_show_product
selective_product	选择商品	ans_show_product
wechat_image	微信图文消息	ans_wechat_image
audio	语音	String 语音的播放链接地址
link	链接	ans_link
image	图片	String 图片的链接地址
custom_card	卡片消息	ans_custom_card
task_button	新任务式对话按钮	ans_task_button
map	地图消息	ans_map
mini_apps_card	小程序卡片	mini_apps_card

ans_selective_table

Path	Type	Description
title	String	表格标题
rowNumber	Integer	表格行数
columnNumber	Integer	表格列数
optionList	Array	表格内容
optionList[].id	Integer	选项Id
optionList[].value	String	选项的值

ans_selective_list

Path	Type	Description
title	String	列表标题
optionList	Array	列表内容
optionList[].id	Integer	选项Id
optionList[].value	String	选项的值

ans_show_product

Path	Type	Description
title	String	商品标题
showSize	Integer	默认展示数量
turnFlag	Integer	商品消息是否可以换组显示 0:禁止 1:可以
productList	Array	商品内容
productList[].id	Integer	商品ID
productList[].name	String	商品名称
productList[].image	String	商品图片
productList[].url	String	商品链接
productList[].infoList	Array	商品信息
productList[].infoList[].info	String	文本
productList[].infoList[].boldFlag	Integer	加粗标识(0或者1)
productList[].infoList[].color	String	颜色

ans_wechat_image

Path	Type	Description
content	String	标准问题内容
coverUrl	String	封面图片路径
description	String	描述
answerUrl	String	答案路径

ans_link

Path	Type	Description
faviconUrl	String	头图的地址
title	String	网站标题
answerUrl	String	答案本身配置的地址

ans_custom_card

Path	Type	Description
id	String	id
name	String	名称
title	String	标题
subTitle	String	副标题
pageType	String	0 假分页 1 真分页
pageNum	String	页数
pageSize	String	页量
cardList	Array	卡片内容
cardList[].id	String	id
cardList[].type	String	卡片类型 1.富文本卡片 2.FAQ推荐列表卡片
cardList[].isHit	String	卡片是否能点击 type=1有效 0否 1是
cardList[].hitType	String	卡片点击效果 type=1&isHit=1有效 1超链接 2回复消息，回复消息是指在聊天窗替用户提问一串文本 3结构化消息，把content富文本内容当做消息发送出去
cardList[].hitContent	String	卡片点击内容 type=1&isHit=1有效 hitType=1是链接地址 hitType=2是需要回复的消息内容
cardList[].hitShowContent	String	hitType=3有效，点击消息发送的消息卡片，如果此字段不为空聊天窗就显示这个，如果为空就显示content，
cardList[].suggestContent	String	FAQ推荐卡片的文案type=2有效
cardList[].suggestList	Array	FAQ推荐的问题列表type=2有效
cardList[].suggestList[].id	Integer	问题的标识id.type=2有效
cardList[].suggestList[].content	Integer	问题的内容.type=2有效
cardList[].suggestList[].type	Integer	问题类型type=2有效

ans_task_button

Path	Type	Description
richText	String	按钮消息说明
buttons	Array	按钮列表
buttons[].flowId	String	所属流程Id
buttons[].nodeId	String	所属流程的节点Id
buttons[].buttonName	String	按钮名称
buttons[].customStyle	String	前端样式.json
buttons[].linkAddress	String	跳转链接地址
buttons[].nextActionType	String	按钮动作类型NEXT_NODE或OPEN_LINK
buttons[].displayLocationType	String	按钮显示位置 DEFAULT_POSITION 或 INPUT_BOX_ABOVE

ans_map

Path	Type	Description
address	String	地图 详细地址
name	String	地点显示的大标题
location	String	经纬度 "11.11,22.22"

mini_apps_card

Path	Type	Description
name	String	小程序名称
appId	String	小程序AppId
appUrl	String	小程序AppIdUrl
miniAppCardType	Integer	区分小程序卡片当前是上传的图片还是输入的picId1：miniAppPicUrl；2:picId
picId	String	picId
miniAppPicUrl	String	miniAppPicUrl

示例

$ curl 'https://km.udesk.cn/api/v1/chat?email=admin@udesk.cn&timestamp=1529402441&sign=08bea0badd00d36c432320fc3760fc419154b40d' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 451714,
  "robotId" : 54,
  "queryContent" : "手机的价格",
  "contentType" : null,
  "chatMode" : null,
  "channel_id" : null,
  "weixin_openid" : null
}'

返回

{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : {
    "sessionId" : 451714,
    "logId" : 793005,
    "ansContent" : "您的问题我会继续努力学习，期待下次为您更好的服务",
    "ansType" : 6,
    "msgType" : "plain",
    "suggestQuestionList" : [ ]
  }
}

请求失败原因

{
  "code": 400,
  "message": "{具体的异常信息}",
  "visible": false
}

message	description
sessionId does not exist! Please reinitialize	对应sessionId的对话不存在
Question content cannot be empty	queryContent的值不能为空

不同data.ansType返回的示例

• ansType是命中的业务类型,此字段和消息内容无直接关系

枚举值	说明
1	返回答案
2	废弃
3	返回建议列表
4	返回寒暄
5	废弃
6	返回未知
7	点击类型消息
8	敏感词
9	消息触发型webhook
10	知识图谱知识点
11	任务式对话
12	资料库对话
13	静默
14	资料库全属性回复
15	知识图谱
16	阅读理解答案
17	阅读理解建议
18	阅读理解引导选择
19	特殊消息
20	数据库问答
21	转人工意图
22	新任务式对话按钮
23	新版任务式对话
24	主动索联
25	企业搜索

智能辅助

请求地址

• POST /v1/assist

请求参数

Request fields

Path	Type	Optional	Description
robotId	Integer	false	机器人id.
channelId	Integer	false	场景id.
queryContent	String	true	问话内容.

请求结果

Path	Type	Description
code	Integer	执行结果码
message	String	执行结果说明
data	Object	会话信息
data.sessionId	Integer	会话id.
data.logId	Integer	机器人返回的log的标识id.
data.ansContent	String	返回对应的答案的内容.
data.ansType	Integer	答案类型
data.flowId	Integer	流程id,返回流程时有效.
data.flowTitle	String	流程标题，返回流程时有效.
data.flowContent	String	流程内容，返回流程时有效.
data.hitQuestion	String	返回召回的问题，.
data.msgType	String	答案的文本类型.
data.switchStaffType	Integer	1.微信渠道显示引导语 2.满足条件转人工.
data.switchStaffTips	String	转人工提示.
data.suggestQuestionList	Array	建议问题列表.
data.suggestQuestionList[].id	Integer	建议问题的标识id.
data.suggestQuestionList[].content	String	建议问题的内容.
data.suggestQuestionList[].type	Integer	建议问题类型
data.suggestQuestionList[].answer	Object	建议问题的答案.
data.suggestQuestionList[].answer.content	String	建议问题的答案内容
data.suggestQuestionList[].answer.type	Integer	建议问题的答案类型
data.suggestQuestionList[].answer.questionId	Integer	件问题问题的答案对应的问题ID
data.suggestQuestionList[].answer.id	Integer	建议问题的答案ID
data.restrictionState	Object	交互量限制状态.
data.restrictionState.exceededFlag	Integer	超限标识【0正常/1已超限】
data.restrictionState.usedCount	Integer	已使用数量
data.restrictionState.totalCount	Integer	限制总量
data.aid	Integer	返回对应的答案的id,问题为FAQ问题时生效

示例

$ curl 'https://km.udesk.cn/api/v1/assist?email=admin@udesk.cn&timestamp=1529402447&sign=c3168ff8ee9db4208d3a6f8a49d4bea7d4058ab3' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 83,
  "channelId" : 83,
  "queryContent" : "你好"
}'

返回

{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : {
    "ansContent" : "我是robot机器人啊",
    "attachmentList" : [ ],
    "hitQuestion" : "你是谁？",
    "msgType" : "rich",
    "suggestQuestionList" : [ ],
    "aid" : 552
  }
}

智能提示接口

请求地址

• POST /v1/smartHint

请求参数

Request fields

Path	Type	Optional	Description
sessionId	Integer	false	会话id.
keyword	String	true	keyword.

请求结果

Path	Type	Optional	Description
code	Integer	true	状态码
message	String	true	返回信息
visible	Boolean	true
data	Object	true	返回内容
data.smartTipList	Array	true	智能提示问题列表.
data.smartTipList[].id	Integer	true	问题的标识id.
data.smartTipList[].content	String	true	问题的内容.
data.smartTipList[].type	Integer	true	问题类型
data.smartTipList[].answer	Object	true	答案.
data.smartTipList[].answer.content	String	true	答案内容
data.smartTipList[].answer.type	Integer	true	答案类型
data.smartTipList[].answer.questionId	Integer	true	答案对应的问题ID
data.smartTipList[].answer.id	Integer	true	答案ID

示例

$ curl 'https://km.udesk.cn/api/v1/smartHint?email=admin@udesk.cn&timestamp=1529402446&sign=a685c1c3881aebe59c79306ef6d288c25fab077b' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450287,
  "keyword" : "社保"
}'

返回

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "smartTipList": [
            {
                "id": 8645,
                "content": "社保怎么办理主引导选择啊",
                "type": 1,
                "answer": {
                    "content": "<p>打电话12345</p>",
                    "type": 2,
                    "id": 4436
                }
            }
        ]
    }
}

请求失败原因

{
  "code": 400,
  "message": "{具体的异常信息}",
  "visible": false
}

message	description
The robot does not exist or has been deleted!	对应robotid的机器人不存在
The scene does not exist	对应channelId的场景不存在
【...】javax.validation.constraints.NotNull.message	【具体字段】不能为空

转人工通知接口

请求地址

• PUT /v1/sessions/:id/switchStaff

请求参数

Path parameters

Parameter	Type	Optional	Description
id	Integer	false	该次会话的会话id（sessionId）.

请求结果

Path	Type	Description
code	Integer	执行状态码
message	String	执行结果信息

示例

$ curl 'https://km.udesk.cn/api/v1/sessions/451718/switchStaff?email=admin@udesk.cn&timestamp=1529402455&sign=d4be213127c62bb5b53dea5f5e52eaad06b2362f' -i -X PUT -H 'Accept: application/json'

返回

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}