# 机器人&知识库

# 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

请求参数:

参数 类型 必填 名称 备注
appid String 接口凭证Id 第三方用户接口调用唯一凭证id
create_time String 时间戳 时间戳,秒,例如 2019-09-25 15:49:33 的时间戳1569397773
sign String 签名 md5(appid+create_time+app_key) sign签名,app_key为秘钥

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 必填 名称 备注
token String token编码
expires_in String 凭证有效时间 单位:秒

时间戳转换参考工具:

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

请求参数:

参数 类型 必填 名称 备注
robot_flag Integer 机器人编号 可以在「设置-机器人-机器人信息」中查看

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_code String 返回信息
item Object 返回对象

item对象:

参数 类型 必填 名称 备注
robot_flag Integer 机器人编号 可以在「设置-机器人-机器人信息」中查看
question_id String 问题id
link_question_num Integer 引导语数量
link_question_list Object 引导语对象
companyid String 公司id
guide_strip String 引导语

link_question_list对象

参数 类型 必填 名称 备注
match_flag Integer 匹配模式:0智能匹配,1完全匹配,2包含匹配,3欢迎语匹配
docid String 词条id
guide_question_disname String 显示名称
guide_question String 标准问法
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

请求参数:

参数 类型 必填 名称 备注
partnerid String 企业自己的用户id,可自行传值
question String 用户问题;多轮会话点击时传入:上轮会话multiDiaRespInfo数据中,只保留template和interfaceRetList的json,其中interfaceRetList集合只保留选中的集合元素
user_nick String 用户昵称
source String 用户渠道 0:pc,1:微信,2:app,3:微博,4:移动网站,9:企业微信,10:小程序
robot_flag String 机器人编号
question_flag String 问题类型 问题类型:点击-1,输入-0,多轮会话中点击-2
request_text String 问题内容 问题内容(questionFlag=0时,传入原问题; questionFlag=1时,传入docId; questionFlag=2时,返回上轮会话的level,conversationId以及outPutParamList对应的值组成的json,例:{"上轮会话中outPutParamList参数":"xxx","level":0,"conversationId":"xxx"} )

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
answer String 答案
suggestions List 推荐问题列表,详见下文
question String 原始问题
docid String 词条id
visitorid String 用户id
cid String 会话id
msgid String 消息体id
stripe String 问题推荐引导语
robot_flag String 机器人编号
answer_type String 机器人回答类型
session_new String 是否是新会话 true:是,false:不是
transfer_type String 触发转人工类型 0:不触发,1:重复提问,2:负向情绪,3:命中关键字
multi_response_info Object 多轮会话返回数据

suggestions对象:

参数 类型 名称 备注
question String 推荐问题的名称
answer String 推荐问题的答案
docid String 推荐问题的词条Id

multi_response_info对象:

参数 类型 名称 备注
remind_question String 机器人提示问题
answer_strip String 答案引导语
interface_ret_list List 接口返回列表
input_content_list String 自定义列表内容 多个以逗号隔开
output_param_list String 下轮会话入参 多个以##隔开
level Integer 轮次
level_name String 轮次名称
question String 原始问题
answer String 答案
ret_code String 调用接口返回码
ret_error_msg String 调用接口返回说明
docid String 推荐问题的词条Id
conversationid String 多轮会话id
template Integer 模板id
end_flag Boolean 多轮会话结束标记

请求示例:

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 String 访客id
cid String 会话id
docid String 词条id
doc_name String 词条名称
robot_flag String 机器人id
status String 评价状态 1:顶,-1:踩
msgid String 消息id
partnerid String 企业自己的用户id,可自行传值
from String 客户来源 0:开放平台;1:web、sdk;2:微信

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

返回参数:

参数 类型 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回数据

item:

参数 类型 名称 备注
ustatus String 用户状态 -2:排队,-1:机器人,0:离线,1-在线

请求示例:

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

请求参数:

参数 类型 必填 名称 备注
key_flag String 1问题,2答案
question_typeid String 词条类型(传-1)
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
question_type_flag String 问题类型,1-全部问题,2-标准问题,3-相似问题
page_no String 当前页码
key_words String 搜索关键字
used_flag String 词条状态,0启用,1手动停用,2系统停用,3过期停用
link_flag String 是否有关联问题,0是,1否
answer_flag String 答案类型:1文本,2图片,3图文,4视频
createid String 词条创建人ID
create_start_time String 创建开始时间
create_end_time String 创建结束时间
updateid String 词条最后更新人ID
update_start_date String 更新开始时间
update_end_date String 更新结束时间
effect_start_date String 生效开始时间
effect_end_date String 生效结束时间
invalid_start_date String 失效开始时间
invalid_end_date String 失效结束时间

返回参数:

参数 类型 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items Object 返回对象
page_count String 总页数
page_no String 当前页码
page_size String 每页条数
total_count String 总条数

items对象:

参数 类型 名称 备注
all_type_name String 分类全路径
answer_desc String 答案内容
answer_flag String 答案类型:1文本,2图片,3图文,4视频
answerid String 答案ID
answer_img String 图文类型的缩略图
answer_txt String 答案纯文本信息
audit_status String 审核状态:0待审核,1永久有效,2指定时间有效
companyid String 公司id
docid String 词条ID
effect_time String 生效时间
invalid_time String 失效时间
link_flag String 是否有关联问题,0是,1无
match_flag String 匹配模式:0智能匹配,1完全匹配,2包含匹配,3欢迎语匹配
questionid String 问题ID
question_title String 问题标题
question_typeid String 问题类型ID
question_type_name String 问题类型名
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
smail_question_num String 相似问法个数
updateid String 更新人ID
update_time String 更新时间
used_flag String 词条状态,0启用,1手动停用,2系统停用,3过期停用

请求示例:

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

请求参数:

参数 类型 必填 名称 备注
parent_typeid String 父级分类id,顶级分类id-1
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
type_flag String 分类类型:1-单轮问题分类(默认);2-多轮问题分类

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items Object 返回对象

items对象:

参数 类型 名称 备注
companyid String 公司id
parent_typeid String 父级分类id
question_typeid String 分类id
question_type_name String 分类名称
type_level String 分类级别
last String 是否是最低级别
type_flag String 分类类型:1-单轮问题分类;2-多轮问题分类

请求示例:

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

请求参数:

参数 类型 必填 名称 备注
docid String 词条Id
robot_flag String 知识库所属机器人:0公共知识库,1机器人一

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
answer_desc String 答案内容
answer_flag String 答案类型:1文本,2图片,3图文,4视频
answerid String 答案ID
answer_img String 图文类型的缩略图
answer_txt String 答案纯文本信息
answer_summary String 图文类型摘要
audit_status String 审核状态:0待审核,1永久有效,2指定时间有效
companyid String 公司id
docid String 词条ID
create_time String 创建时间
effect_time String 生效时间
link_question_list List 关联问题列表,详见下文
link_question_num String 关联问题个数
linked_flag String 是否被其他问题关联,1是,0无
match_flag String 匹配模式:0智能匹配,1完全匹配,2包含匹配,3欢迎语匹配
questionid String 问题ID
question_title String 问题标题
question_typeid String 问题类型ID
question_type_name String 问题类型名
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
smail_question_num String 相似问法个数
updateid String 更新人ID
update_time String 更新时间
used_flag String 词条状态,0启用,1手动停用,2系统停用,3过期停用

linkQuestionList对象:

参数 类型 名称 备注
docid String 关联问题词条Id
link_name String 显示名称
link_question_title String 知识库本身名称

请求示例:

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/add_robot_doc

请求参数:

参数 类型 必填 名称 备注
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
question_title String 标准问题
match_flag String 匹配模式:0智能匹配,1完全匹配,2包含匹配
answer_desc String 答案内容
question_typeid String 词条分类id
used_flag String 词条状态:0开启,1停用
audit_status String 有效状态:1永久有效;2指定时间有效
effect_time String 生效时间,格式:yyyy-MM-dd HH:mm:ss
invalid_time String 失效时间,格式:yyyy-MM-dd HH:mm:ss

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

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.9、修改知识库词条

接口说明:

接口类型:主动调用接口

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

请求方式:

POST

请求地址:

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

请求参数:

参数 类型 必填 名称 备注
docid String 词条id
robot_flag String 知识库所属机器人:0公共知识库,1机器人一
questionid String 问题id
question_title String 标准问题
match_flag String 匹配模式:0智能匹配,1完全匹配,2包含匹配
answerid String 答案id
answer_desc String 答案内容
question_typeid String 词条分类id
used_flag String 词条状态:0开启,1停用
audit_status String 有效状态:1永久有效;2指定时间有效
effect_time String 生效时间,格式:yyyy-MM-dd HH:mm:ss
invalid_time String 失效时间,格式:yyyy-MM-dd HH:mm:ss

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

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.10、删除知识库词条

接口说明:

接口类型:主动调用接口

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

请求方式:

POST

请求地址:

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

请求参数:

参数 类型 必填 名称 备注
docid String 词条id
robot_flag String 知识库所属机器人:0公共知识库,1机器人一

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息

请求示例:

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、使用场景

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

# 3.2、如何设置

# 设置项说明

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

图片

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

http://www.test.com/Order

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

图片

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

# 设置示例

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

添加参数:

参数名称 长度限制 参数说明 分隔符
key 40 调用接口 #
cityname 10 查询城市名称 #

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

# 触发调用说明

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

# 参数传递

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

# 固定参数

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

# 自定义参数

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

# 3.3、接口返回格式

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

名称 类型 说明
ret_code int 查询状态返回码,0为查询正确返回,1为查询错误返回
ret_message string 查询返回结果,即展示给用户的信息,支持基本的html标签,包括图片、文字字体及排版代码等。

接口返回数据示例:

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

# 3.4、其他注意事项

# 接口调用超时时长

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

# 编码格式

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

# 返回答案长度

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

# 4、错误编码

# 4.1、操作成功

业务操作成功。

错误编码 错误说明
000000 操作成功(除此编码以外的编码为错误编码)

# 4.2、系统异常

系统服务异常。

错误编码 错误说明
900001 token为空
900002 token已失效,请重新获取
900003 signature错误
900004 没有找到公司的api配置信息
999999 系统未知异常

# 4.3、业务异常

业务异常(需要修改接口时确定)

错误编码 错误说明
110055 机器人参数不能为空
110050 请选择分类
110075 公司不能为空
110007 分类不存在
110026 词条不能为空
110082 多机器人服务已到期,如需继续使用公共知识库,请联系客服人员进行续期
110001 问题标题不能为空
110021 问题过长,最多可输入240个字符
110063 匹配模式不能为空
110065 答案不能为空
110022 答案过长
110050 请选择分类
110058 生效类型不能为空
110019 词条状态为空或有误
110087 请输入有效的接口URL,最多100个字符
110091 最多添加10个参数
110093 请填写完整的参数属性
110094 请输入有效的参数名称,最多20个字符
110095 请输入1~50的数字作为长度限制
110096 请输入有效的参数说明,最多100个字符
110088 请输入有效的token,10~32位英文或数字组合
110089 请输入有效的调用说明,最多500个字符
110059 生效时间不能为空
110136 时间范围不正确
110002 添加失败,标准问法或者相似问法重复
110030 与相似问法或标准问法重复
110066 最多添加10000个相似问法
110105 完全匹配模式下单词条相似问法条数不得超过200条
110106 包含匹配模式下单词条相似问法条数不得超过200条
110125 多轮会话的相似问法条数不得超过50条
110024 相似问法不能为空
110028 相似问法过长,最多可输入240个字符
110029 相似问法或标准问法重复
110025 相似问法重复
110067 最多添加20个关联问题
110031 被关联词条或者关联问题不能为空
110037 相关问题文案过长
110034 此词条不能被关联
110057 词条启用失败,获取企业数据错误
110006 词条超过上限
110026 词条不能为空
110012 操作词条不存在
110101或400101 当前问题的标准问法已被加入永久忽略列表,机器人不能对此问题进行智能学习。若需要机器人针对当前问题进行智能学习,请在永久忽略列表中删除对应问法。