机器人 & 知识库

1、接口声明

在调用接口时必须在https请求的header中携带"token"参数。

token是智齿客服接口开放平台全局唯一的接口调用凭据。
开发者在调用各业务接口时都需使用token，开发者需要进行妥善保存。token的存储至少要保留32个字符空间。token的有效期目前为24个小时，需定时刷新，或根据接口返回的token失效提示，进行重新获取。请求token接口，无论token是否存在，都会返回新的token，并重置token的过期时间(目前24小时)。

token使用方式说明：
1、开发者需要统一获取和管理token，在调用智齿客服各个业务开放接 口时都应该使用同一个的token，不应该每个业务都刷新获取新的 token，否则容易导致token失效，影响接口的正常调用；
2、目前token的有效期通过返回的expire_in来传达，目前是86400 秒之内的值。开发者需要根据这个有效时间提前去刷新新token。
3、开发者需要根据接口返回的token失效提示，进行重新获取token。

2、接口调用

2.1、获取访问token编码

接口说明：

获取API开放接口token，此token仅适用于智齿开放平台 5.0版本全部API接口 。API接口中的参数 appid, app_key 请联系智齿售后人员获取。

请求方式：

GET

请求地址：

https://www.sobot.com/api/get_token

请求参数：

返回参数：

item对象：

时间戳转换参考工具：

http://tool.chinaz.com/Tools/unixtime.aspx

sign签名生成示例：

例如，appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") 为 258eec3118705112b2c53dc8043d4d34。

请求示例：

curl https://www.sobot.com/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

返回示例：

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

2.2、获取常见问题

接口说明：

接口类型：主动调用接口。

接口作用：可以调用在智齿后台配置的指定机器人的常见问题列表和引导语。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/get_robot_guide

请求参数：

返回参数：

item对象：

link_question_list对象

curl https://www.sobot.com/api/robot/5/get_robot_guide 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: application/json' 
-d '
{
   "robot_flag": "1"
}'

返回示例：

{
   "items": [],
   "item": {
       "robot_flag": 1,
       "question_id": "078726f1435b4218b9733afe2433b9fe",
       "link_question_num": 4,
       "link_question_list": [
           {
               "sort_no": 1,
               "match_flag": 0,
               "docid": "1b06cc8839574dc487bf658f0033bfb1",
               "guide_question_disname": "违约金/滞纳金是否可以开具发票？",
               "guide_question": "违约金/滞纳金是否可以开具发票？"
           },
           {
               "sort_no": 4,
               "match_flag": 0,
               "docid": "9b66fd499ff946df8213868bece0b0e3",
               "guide_question_disname": "北京有按天收费的房子么",
               "guide_question": "北京有按天收费的房子么"
           }
       ],
       "companyid": "0a53403cb9b34d528bdc11df69c283ff",
       "guide_strip": "<p>测试引导语！！！</p>"
   },
   "ret_code": "000000",
   "ret_msg": "查询成功！"
}

2.3、用户咨询机器人

接口说明：

接口类型：主动调用接口。

接口作用：可通过调用该接口实现以用户的身份咨询机器人并获取答案。

请求方式：

POST

请求地址：

https://www.sobot.com/api/chat/5/user/robot_chat

请求参数：

question 参数详解

  单轮：传入用户问题；
  多轮：需要根据上轮返回值中multiDiaRespInfo字段确定传入内容。
	multiDiaRespInfo中关键字段为：interfaceList和inputContent，同一轮返回值中两者只会存在一个。
	1）如果上轮返回interfaceList,只保留template和interfaceRetList的json，其中interfaceRetList集合只保留选中的集合元素，例：
```json
		上轮返回：{
					"template":0,
					"question":"模板一",
					"level":0,
					"conversationId":"5fcb4cb5-2078-41c7-bb9d-8fbf57464c94",
					"docId":"1b8b2dcc4a8243649fa49744b9cf362b",
					"groupId":"9a38730078354d4a832a6c621483ad9d",
					"remindQuestion":"请选择电影:",
					"endFlag":false,
					"levelName":"电影",
					"retCode":"000000",
					"clickFlag":1,
					"interfaceRetList":[
						{
							"summary":"好看的电影，不要错过",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"2020年上映",
							"label":"20.01元",
							"title":"变形金刚III"
						},
						{
							"summary":"优秀电影",
							"thumbnail":"https://i01.lw.aliimg.com/media/lADODuM9KM0E2s0E1w_1239_1242.jpg",
							"anchor":"http://www.sina.com",
							"movieId":"3",
							"tag":"未上映",
							"label":"60.00",
							"title":"猩球崛起"
						}
					],
					"outPutParamList":"title#movieId"
				}
			客户选中title为"变形金刚III"的选项，则传入数据为：{
					"template":0,					
					"interfaceRetList":[
						{
							"summary":"好看的电影，不要错过",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"2020年上映",
							"label":"20.01元",
							"title":"变形金刚III"
						}
					]
				}

2）如果上轮返回inputContent，则直接传入选中的值。

		例：{
				"template":0,
				"question":"我想买手机",
				"level":0,
				"conversationId":"a4bb45ed-594e-4953-b74e-e2f902f1337f",
				"docId":"022e96da2f8346b7bfb0efb400a9c558",
				"groupId":"9a38730078354d4a832a6c621483ad9d",
				"remindQuestion":"请选择品牌",
				"endFlag":false,
				"levelName":"品牌",
				"retCode":"000000",
				"inputContentList":"华为,苹果,小米",
				"outPutParamList":"品牌"
			}
		选中inputContentList里的华为，则传入数据为：华为；

request_text参数详解 单轮：非必填字段； 多轮：必填，需要根据上轮返回值中multiDiaRespInfo字段确定传入内容。 multiDiaRespInfo中关键字段为：interfaceList和inputContent，同一轮返回值中两者只会存在一个。 1）如果上轮返回interfaceList,返回上轮会话的level，conversationId以及outPutParamList对应的值组成的json。返回上轮会话的level，conversationId以及outPutParamList对应的值组成的json，例：{"上轮会话中outPutParamList参数":"xxx","level":0,"conversationId":"xxx"} ）例：

		上轮返回：{
					"template":0,
					"question":"模板一",
					"level":0,
					"conversationId":"5fcb4cb5-2078-41c7-bb9d-8fbf57464c94",
					"docId":"1b8b2dcc4a8243649fa49744b9cf362b",
					"groupId":"9a38730078354d4a832a6c621483ad9d",
					"remindQuestion":"请选择电影:",
					"endFlag":false,
					"levelName":"电影",
					"retCode":"000000",
					"clickFlag":1,
					"interfaceRetList":[
						{
							"summary":"好看的电影，不要错过",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"2020年上映",
							"label":"20.01元",
							"title":"变形金刚III"
						},
						{
							"summary":"优秀电影",
							"thumbnail":"https://i01.lw.aliimg.com/media/lADODuM9KM0E2s0E1w_1239_1242.jpg",
							"anchor":"http://www.sina.com",
							"movieId":"3",
							"tag":"未上映",
							"label":"60.00",
							"title":"猩球崛起"
						}
					],
					"outPutParamList":"title#movieId"
				}

			客户选中title为"变形金刚III"的选项，则传入数据为：{
					"level":0,
					"conversationId":"5fcb4cb5-2078-41c7-bb9d-8fbf57464c94",				
					"movieId":"1",
					"title":"变形金刚III"
				}

2）如果上轮返回inputContent，则返回上轮会话的level，conversationId以及outPutParamList对应的值组成的json。

		例：{
				"template":0,
				"question":"我想买手机",
				"level":0,
				"conversationId":"a4bb45ed-594e-4953-b74e-e2f902f1337f",
				"docId":"022e96da2f8346b7bfb0efb400a9c558",
				"groupId":"9a38730078354d4a832a6c621483ad9d",
				"remindQuestion":"请选择品牌",
				"endFlag":false,
				"levelName":"品牌",
				"retCode":"000000",
				"inputContentList":"华为,苹果,小米",
				"outPutParamList":"品牌"
			}
		选中inputContentList里的华为，则传入数据为：{
				"level":0,
				"conversationId":"a4bb45ed-594e-4953-b74e-e2f902f1337f",
				"品牌":"华为"
				} 
				

返回参数：

item对象：

suggestions对象：

multi_response_info对象：

请求示例：

curl https://www.sobot.com/api/chat/5/user/robot_chat 
-X POST 
-H 'content-type: application/json' 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-d '
{
	"partnerid" : "xx",
	"question" : "xx"
}'

返回示例：

{
    "item":{
        "answer":"xx",
        "suggestions":[
            {
            	"question":"xx",
            	"answer":"xx",
            	"docid":"xx"
            }
        ],
        "question":"xx",
        "docid":"xx",
        "userid":"xx",
        "cid":"xx",
        "msgid":"xx",
        "stripe":"xx",
        "robot_flag":"1",
        "answer_type":"1",
        "session_new":"true",
        "transfer_type":"1"
    },
    "ret_code":"000000",
    "ret_msg":"成功"
}

2.4、机器人回答评价

接口说明：

接口类型：主动调用接口。

接口作用：通过主动调用接口来进行机器人回答的评价（非会话评价）。

请求方式：

POST

请求地址：

https://www.sobot.com/api/chat/5/user/robot_feedback

请求参数：

注：如没有visitorid,可传入partnerid、from三个字段代替

返回参数：

item:

请求示例：

curl https://www.sobot.com/api/chat/5/user/robot_feedback 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: application/json' 
-d '
{
    "cid": "a09b71ae2abd4604aba1c9961bc31095",
    "msgid": "2cfd756f0077406ea22d1efe75555c55",
    "docid": "317f5b28887544d0be69f7e1520b269d",
    "doc_name": "视频和文本",
    "robot_flag": "1",
    "status": "1",
    "visitorid": "ab48f1e755ac766d8732501a3ef1a116"
}'

返回示例：

{
    "item": {
        "ustatus": "-1"
    },
    "ret_code": "000000",
    "ret_msg": "成功"
}

2.5、查询知识库词条列表

接口说明：

接口类型：主动调用接口。

接口作用：可通过调用该接口来查询某个知识库所有知识条目的列表。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/search_doc_list

请求参数：

返回参数：

items对象：

请求示例：

curl https://www.sobot.com/api/robot/5/search_doc_list 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: "application/json' 
-d '
{
	"key_flag": "1",
	"question_typeid": "-1",
	"robot_flag": "1",
	"page_no": "1",
	"key_words": "xx",
	"used_flag": "0",
	"link_flag": "1",
	"answer_flag": "1",
	"createid": "xx",
	"create_start_time": "yyyy-MM-dd",
	"create_end_time": "yyyy-MM-dd",
	"updateid": "xx",
	"update_start_date": "yyyy-MM-dd",
	"update_end_date": "yyyy-MM-dd",
	"effect_start_date": "yyyy-MM-dd",
	"effect_end_date": "yyyy-MM-dd",
	"invalid_start_date": "yyyy-MM-dd",
	"invalid_end_date": "yyyy-MM-dd"
}'

返回示例：

{
	"items" : [
		{
			"all_type_name" : "xx",
			"answer_desc" : "xx",
			"answer_flag" : "1",
			"answerid" : "xx",
			"answer_img" : "xx",
			"answer_txt" : "xx",
			"audit_status" : "1",
			"companyid" : "xx",
			"docid" : "xx",
			"effect_time" : "1481731200",
			"invalid_time" : "4102415999",
			"link_flag" : "1",
			"match_flag" : "0",
			"questionid" : "xx",
			"question_title" : "xx",
			"question_typeid" : "xx",
			"question_type_name" : "xx",
			"robot_flag" : "1",
			"smail_question_num" : "0",
			"updateid" : "xx",
			"update_time" : "1481789852",
			"used_flag" : "0"
		} 
	],
	"page_count" : "3",
	"page_no" : "1",
	"page_size" : "15",
	"total_count" : "40",
	"ret_code":"000000",
	"ret_msg":"操作成功"
}

2.6、查询知识库分类列表

接口说明：

接口类型：主动调用接口。

接口作用：可通过调用该接口来查询某个知识库中的分类。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/search_question_type_list

请求参数：

返回参数：

items对象：

请求示例：

curl https://www.sobot.com/api/robot/5/search_question_type_list 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: application/json' 
-d '
{
	"parent_typeid": "-1",
	"robot_flag": "1",
	"type_flag": "1"
}'

返回示例：

{
	"items" : [
		{
			"companyid" : "xx",
			"parent_typeid" : "xx",
			"question_typeid" : "xx",
			"question_type_name" : "xx",
			"type_level" : "1",
			"last" : "true",
			"type_flag" : "1"
		} 
	],
    "ret_code":"000000",
    "ret_msg":"操作成功"
}

2.7、查询知识库词条

接口说明：

接口类型：主动调用接口。

接口作用：可通过调用该接口来查询某个知识条目的详细信息。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/query_doc_detail

请求参数：

返回参数：

item对象：

linkQuestionList对象：

请求示例：

curl https://www.sobot.com/api/robot/5/query_doc_detail 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: application/json' 
-d '
{
	"docid":"xx",
	"robot_flag":"1"
}'

返回示例：

{
	"item" : {
		"answer_desc" : "xx",
		"answer_flag" : 1,
		"answerid" : "xx",
		"answer_img" : "xx",
		"answer_txt" : "xx",
		"answer_summary" : "xx",
		"audit_status" : "1",
		"companyid" : "xx",
		"docid" : "xx",
		"create_time" : "2017-01-01 08:00:00",
		"effect_time" : "2017-01-01",
		"link_question_list" : [
			{
				"docid" : "xx",
				"link_name" : "xx",
				"link_question_title" : "xx"
			}
		],
		"link_question_num" : "2",
		"linked_flag" : "1",
		"match_flag" : "0",
		"questionid" : "xx",
		"question_title" : "xx",
		"question_typeid" : "xx",
		"question_type_name" : "xx",
		"robot_flag" : "1",
		"smail_question_num" : "0",
		"updateid" : "xx",
		"update_time" : "2017-01-01 08:00:00",
		"used_flag" : "0"
	},
	"ret_code":"000000",
    "ret_msg":"操作成功"
}

2.8、查询相似问

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/query_doc_similar_list

请求参数：

返回参数：

items对象

请求示例：

curl https://www.sobot.com/api/robot/5/query_doc_similar_list 
-X POST 
-H 'token:222222222222233333333344444556ab' 
-H 'content-type: application/json' 
-d '
{
  "docid":"11111111111111111111111114388f2e6",
     "key_words":"咸",
     "robot_flag":1,
     "page_no":1
}'

返回示例：

{
    "page_no": 1,
    "page_count": 1,
    "total_count": 1,
    "page_size": 15,
    "items": [
        {
            "question_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "company_id": "xxxxxxxxx",
            "doc_id": "11111111111111111111111114388f2e6",
            "question_title": "脆咸萝卜干",
            "create_service_id": "xxxxxxxxxxxxxx",
            "create_service_name": "张三",
            "create_time": 1626674559,
            "type_flag": 2,
            "question_status": 0,
            "update_service_id": "xxxxxxxxxxxxxx",
            "update_service_name": "张三",
            "update_time": 1626674559,
            "robot_flag": 1
        }
    ],
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

2.9、添加知识库词条

接口说明：

接口类型：主动调用接口。

接口作用：可通过调用该接口来添加一个知识条目。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/add_robot_doc

请求参数：

返回参数：

请求示例：

curl https://www.sobot.com/api/robot/5/add_robot_doc 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'content-type: application/json' 
-d '
{
	"robot_flag":"1",
	"question_title":"xx",
	"match_flag":"1",
	"answer_desc":"xx",
	"question_typeid":"xx",
	"used_flag":"0",
	"audit_status":"1",
	"effect_time":"xx",
	"invalid_time":"xx"
}'

返回示例：

{       
	"ret_code": "000000",
	"ret_msg": "操作成功！"
}

2.10、修改知识库词条

接口说明：

接口类型：主动调用接口

接口作用：可通过调用该接口来进行某个知识条目的修改操作。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/update_robot_doc

请求参数：

返回参数：

请求示例：

curl https://www.sobot.com/api/robot/5/update_robot_doc 
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
"docid":"xx",
"robot_flag":"xx",
"questionid":"xx",
"question_title":"xx",
"match_flag":"xx",
"answerid":"xx",
"answer_desc":"xx",
"question_typeid":"xx",
"used_flag":"xx",
"audit_status":"xx",
"effect_time":"xx",
"invalid_time":"xx"
}'

返回示例：

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

2.11、删除知识库词条

接口说明：

接口类型：主动调用接口

接口作用：可通过调用该接口来删除知识库中的某个知识条目。

请求方式：

POST

请求地址：

https://www.sobot.com/api/robot/5/delete_robot_doc

请求参数：

返回参数：

请求示例：

curl https://www.sobot.com/api/robot/5/delete_robot_doc
-X POST 
-H 'token:c87c0dbac8c24261b9a4335fa5a51448' 
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
	"docid":"xx",
	"robot_flag":"xx"
	}'

返回示例：

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

3、错误编码

3.1、操作成功

业务操作成功。

3.2、系统异常

系统服务异常。

3.3、业务异常

业务异常（需要修改接口时确定）

4、多轮会话接口调用

4.1、应用场景

多轮会话的接口有以下两种应用场景：仅获取变量、获取消息内容。

仅获取变量

应用场景是在命中多轮问题后，先调用一次接口获取变量，来作为后续节点提供判断依据。比如回答「社保问题」时，需要从接口调取员工的社保所在地。接口获取的内容不直接用于对话交互。

设置入口对应以下截图。

获取消息内容

使用场景为机器人发送的内容需要从接口中获取。比如「查物流」时需要让用户选择订单列表；「开发票」时，将收集的信息推送至发票接口并告知客户是否成功。

下图为系统配置截图（下图为答案节点的接口配置，和条件节点稍有差异）。

4.2、模板样式和参数概览

模板一

模板二

模板三

模板四

自定义模板

将希望机器人发送的消息对应至tempStr参数，详见「请求参数」章节

不选模板

将希望机器人发送的消息对应至title参数，详见「请求参数」章节

4.3、接口配置

在多轮中调用接口时，需要先按截图路径配置接口。

您可以自定义Header参数、请求参数、输出参数。

自定义请求参数可以从多轮收集的变量中关联。输出参数将辅助多轮机器人进行后续的条件判断。

4.4、请求参数

如上方截图，partnerId和multiParams为固定入参，同时您可以自定义参数（多轮中收集的信息可以关联到自定义参数）

请求示例

curl https://xxxx.com/api/xxxx
-X POST
-H "Content-Type:application/x-www-form-urlencoded" 
-H "自定义Header1:header值1" //后台自定义的header参数1
-H "自定义Header2:header值2" //后台自定义的header参数2
-D "partnerId=xxx&multiParams={\"xx\":\"xx\"}&token=xxxx&source=0&robotNo=1&docId=xxxx&自定义参数名称1=值1&自定义参数名称2=值2//请求参数部分，分为固定参数和后台自定义参数两部分

4.5、返回参数

多轮使用场景有多种情况，请您统一使用 list 形式，按以下规范返回，包括不涉及列表的情况（自定输出义参数也请放置在list中）。返回参数必须在5秒内推送，否则机器人将按未找到答案处理。

请注意，title参数必传，详见下文示例

返回示例-正常情况

"code":"000000"表示正常情况 ， 比如查快递时，用户名下有订单。规范如下：

{
    "code": "000000", // '000000'表示成功 
    "robotMsg": "机器人消息", //如传入，将替代界面配置的「机器人提问引导」「答案引导文案」。可以在文案中加入“\n”实现换行效果（限新版PC/H5（接入url含“V2”）、2.8.2及以上版本SDK）。注意，模板类型，模板类型选择「不选模板」时，请将机器人发送的文本内容通过下面的"title"参数传输 
    "list": [
        {
            "id": "参数ID",
            "title": "标题", //必须返回参数 。 模板类型选择「不选模板」时，请将机器人发送的文本内容通过本参数传输 
            "summary": "摘要",
            "tag": "标签 （可显示多个项）",
            " label": "价格||评分||多少人想看||人数等一切非多个标签的展示项",
            "thumbnail": "预览图片地址",
            "anchor": "点击跳转地址",
        },
        {
            "id": "参数ID",
            "title": "标题",
            "summary": "摘要",
            "tag": "标签 （可显示多个项）",
            " label": "价格||评分||多少人想看||人数等一切非多个标签的展示项",
            "thumbnail": "预览图片地址",
            "anchor": "点击跳转地址"
        }
    ]
}

返回示例-异常情况

"code":"000001"表示异常情况，比如查快递时，用户名下没有订单。

此时机器人将发送e rrorMsg返回的内容，并将终止多轮对话。

{
    "code": "000001", // '000001'表示接口返回自定义异常提示信息 
    "errorMsg": "异常信息描述" //机器人展示内容 
}

4.6、案例

第三方的接口如果需要前后关联，就需要通过自定义参数来完成。比如 「我要看电影」这个多轮，第一个节点是「城市节点：请您点击所在的城市」，第二个节点是「影院节点：请您选择电影院」。此时电影院的可选列表取决于第一轮选择的城市，需要将第一轮接口的参数进行传递。

那么 ，第一个 节点获取「获取城市接口」返回的接口结果是：

{
    "code": "000000 '000000代表成功'",
    "list": [
        {
            "title": "北京",
            "cityId": "1" //城市 ID 
        },
        {
            "title": "上海",
            "cityId": "2" //城市 ID 
        }
    ]
}

在配置「获取电影院接口」时， 需要加入 cityId 这个 请求 参数

在 配置选择影院的节点时， 需要将 「城市」节获取的内容，关联到「获取电影院接口」的自定义请求参数cityId上

如上所示，当用户 在「城市」节点 点选了 「 北京 」 ， 「获取电影院接口」 会 以 cityId = 1 去请求可选的影院。

5、单轮会话接口调用

5.1、应用场景

智齿客服机器人除了可以进行基于知识库内容的问答外，还能够进行基于第三方接口的信息调用。
比如快递公司希望用户可以在与机器人沟通时自助查询快递情况，就可以针对此场景在知识库中设立一个机器人调用快递查询接口的问题。
当用户交互时若触发该问题，机器人就可以将用户希望查询的快递单号传递给查询接口，再将查询接口返回的信息发送给用户，实现用户的自助查询。
比如，用户输入“订单查询：12345678”，机器人就会调用订单查询接口，并将用户信息以及用户输入的订单号“12345678”传递给查询接口，若查询接口正常返回了查询结果，机器人将会把查询结果展示给用户。

5.2、如何设置

设置项说明

对于企业版以及更高级版本的用户，在知识库中点击添加问题时，可以看到能够选择“接口调用”类型。选择后，将出现相关的设置项。

其中各设置项的含义如下：
标准问法：用户输入中触发接口查询的关键字。该关键字必须在一次输入的开头。
比如，设置标准问法为“订单查询”，则“订单查询：12345”可以正确触发接口调用，“能不能订单查询”将不会触发接口调用。接口调用问法的匹配优先级会高于其他问法，为关键字匹配，但为了避免造成知识库维护的混乱，请尽量避免与其他问题的标准问法一致或有包含关系。
接口URL：调用接口的地址。比如：

http://www.test.com/Order

参数：需要机器人从用户输入内容中抽取的参数，并在调用接口时进行传递。
参数名称：传递该参数时使用的参数名，比如，OrderID，机器人在调用接口时将给OrderID参数赋值，并进行传递。
长度限制：限制此参数的长度，若用户输入的参数超过此长度，机器人将向用户展示调用说明。
参数说明：对此参数的备注说明信息。机器人不会使用此信息。
分隔符：与前一个参数或标准问法关键字区分开的符号，可以设置为空格，冒号，逗号，下划线，括号等。

token：调用接口时传递的token，可随机生成，也可自定义。可作为智齿客服机器人在调用接口时的身份认证。
调用说明：当用户触发了接口调用，但未正确输入需要的参数时，机器人将把此处设定的内容展示给用户。
超时说明：在调用接口时若返回错误信息或超时，机器人将把此处设定的内容展示给用户。
选择分类：该问题在知识库中的分类。
生效时间：该问题的生效时间。
启用状态：该问题的启用状态。

设置示例

标准问法：天气查询
接口URL：http://www.test.com/weather/query?

添加参数：

token：de8devfjtf8cj7eogi9el（随机生成）
调用说明：如果您想天气查询请按照如下格式提问：天气查询#ddXXXXXXXXXXXXXXXX12dd#上海
超时说明：网络连接超时，请稍后重试

触发调用说明

对于上例，用户在输入不同内容时的情况说明。
“查一下天气”（不触发接口调用）
“怎么天气查询呢？”（不触发接口调用）
“天气查询”（触发接口调用，但参数输入错误，机器人返回调用说明内容给用户）
“天气查询：北京”（触发接口调用，但参数输入错误，机器人返回调用说明内容给用户）
“天气查询#123456#上海”（触发接口调用，机器人将调用第三方接口，并将123456作为key参数值，上海作为cityname参数值进行传递）

参数传递

在进行接口调用时，机器人会以POST方式传递参数。

固定参数

固定参数是指无论如何进行设置，在调用接口时机器人都会传递的参数。包括：
partnerid：用户对接ID，有关信息可以查询《智齿客服接入指南》
token：在设置时填写的Token字段

自定义参数

自定义参数是指在设置时添加的参数，机器人将按照用户输入顺序及分隔符提取参数，若参数提取正确，将向接口进行传递。

5.3、接口返回格式

接口返回结果应为JSON格式，应包含以下参数：

接口返回数据示例：

{
    "ret_code": 0,
    "ret_message": "今天是星期3，农历二月初四，现在温度为：5℃，湿度为：12，风向为：北风，风力为：3级。"   
}

5.4、其他注意事项

接口调用超时时长

当调用接口在2000毫秒内没有返回有效结果时，机器人将判定接口调用超时，向用户展示调用超时说明。

编码格式

在进行接口调用时，机器人将以UTF-8格式进行编码传递参数。对于接口返回数据，也应使用UTF-8编码。

返回答案长度

建议返回的答案内容长度在2000字以内。过长的答案会影响用户阅读的效率，也不利于进行展示。