开发者文档
智齿科技
2022-05-19
目录

知识库 API

# 知识库 API

# 接口声明

在调用接口时必须在 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 来传达，目前是 86,400 秒之内的值。开发者需要根据这个有效时间提前去刷新新 Token。
3、开发者需要根据接口返回的 Token 失效提示，进行重新获取 Token。

# 接口调用

# ● 获取访问 Token 编码

接口说明：

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

请求方式：

GET

请求地址：

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

请求参数：

参数 类型 必填 描述
appid String 是 接口凭证 Id，第三方用户接口调用唯一凭证 id
create_time String 是 时间戳
sign String 是 签名

返回参数：

参数 类型 必填 描述
ret_code String 是 返回编码
ret_msg String 是 返回信息
item Object 否 返回对象

item 对象：

参数 类型 必填 描述
token String 是 token 编码
expires_in String 是 凭证有效时间，单位：秒

时间戳转换参考工具：

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

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
1

返回示例：

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}
1
2
3
4
5
6
7
8
# ● 查询知识库词条列表

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
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 否 失效结束时间
timezone 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 知识库配置的答案内容，格式为 HTML
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-过期停用，-2：隐藏状态

请求示例：

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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

返回示例：

{
	"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":"操作成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# ● 查询知识库分类列表

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
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"
}'
1
2
3
4
5
6
7
8
9
10

返回示例：

{
	"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":"操作成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# ● 查询知识库词条

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
docid String 是 词条 id
robot_flag String 是 知识库所属机器人：0-公共知识库，1-机器人一
timezone String 是 时区

返回参数：

参数 类型 必填 描述
ret_code String 是 返回编码
ret_msg String 是 返回信息
item Object 否 返回对象

item 对象：

参数 类型 必填 描述
answer_desc String 知识库配置的答案内容，格式为 HTML
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 生效时间
invalid_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-过期停用
create_timeabs String 创建时间戳绝对值
update_timeabs String 更新时间戳绝对值
effect_timeabs String 生效时间戳绝对值
invalid_timeabs String 失效时间戳绝对值

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"
}'
1
2
3
4
5
6
7
8
9

返回示例：

{
	"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",
        "create_timeabs" : "1676426790000",
        "update_timeabs" : "1676459190000",
        "effect_timeabs" : "1676460967694",
		"used_flag" : "0"
	},
	"ret_code":"000000",
    "ret_msg":"操作成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# ● 查询相似问题

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
docid String 是 词条 id
robot_flag Integer 是 知识库所属机器人：0-公共知识库，1-机器人一
key_words String 否 搜索关键字
page_no Integer 是 当前页码

返回参数：

参数 类型 必填 描述
ret_code String 是 返回编码
ret_msg String 是 返回信息
page_no Integer 是 页码
page_count Integer 是 页数
total_count String 是 总量
page_size String 是 页面容量
items Object 否 返回对象

items 对象

参数 类型 必填 描述
question_id String 问题 id
company_id String 公司 id
doc_id String 词条 id
quection_title String 问法标题
create_service_id String 创建者 id
create_service_name String 创建者名
create_time Long 创建时间
type_flag Integer 问题类别，1-标准问法，2-相似问法
question_status Integer 问题状态，-2:隐藏状态 0:正常，1:删除
update_service_id String 修改者 id
update_service_name String 修改者名
update_time Long 修改时间
robot_flag Integer 知识库所属机器人：0-公共知识库，1-机器人一

请求示例：

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
}'
1
2
3
4
5
6
7
8
9
10
11

返回示例：

{
    "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": "操作成功"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# ● 添加知识库词条

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
robot_flag String 是 知识库所属机器人：0-公共知识库，1-机器人一
question_title String 是 标准问题
match_flag String 是 匹配模式：0-智能匹配，1-完全匹配，2-包含匹配
answer_desc String 是 知识库配置的答案内容，格式为 HTML
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
timezone String 否 时区

返回参数：

参数 类型 必填 描述
ret_code String 是 返回编码
ret_msg String 是 返回信息
item String 是 词条ID

请求示例：

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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

返回示例：

{       
	"ret_code": "000000",
	"ret_msg": "操作成功！",
	"item": "xxxxx"
}
1
2
3
4
5
# ● 修改知识库词条

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
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 是 知识库配置的答案内容，格式为 HTML
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
timezone String 否 时区

返回参数：

参数 类型 必填 描述
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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

返回示例：

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}
1
2
3
4
# ● 删除知识库词条

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
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"
	}'
1
2
3
4
5
6
7
8

返回示例：

{
    "ret_code": "000000",
    "ret_msg": "操作成功"
}
1
2
3
4

# 错误编码

# ● 操作成功
错误编码 错误说明
000000 操作成功（除此编码以外的编码为错误编码）
# ● 系统异常
错误编码 错误说明
900001 token 为空
900002 token 已失效，请重新获取
900003 signature 错误
900004 没有找到公司的 api 配置信息
999999 系统未知异常
# ● 业务异常
错误编码 错误说明
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 当前问题的标准问法已被加入永久忽略列表，机器人不能对此问题进行智能学习。若需要机器人针对当前问题进行智能学习，请在永久忽略列表中删除对应问法。
上次更新: 2023/10/18 14:03:03

← 电商平台 API→

最近更新
01
运营支持 API
03-03
02
CRM 对接方案
12-05
03
大模型机器人API
09-09
更多文章>
Theme by Vdoing