开发者文档
智齿科技
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
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/get_robot_guide
1

请求参数：

参数 类型 必填 描述
robot_flag Integer 是 机器人编号
faqid Number 否 常见问题组 ID

返回参数：

参数 类型 必填 描述
ret_code String 是 返回编码
ret_msg 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"
}'
1
2
3
4
5
6
7
8

返回示例：

{
   "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": "查询成功！"
}
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
# ● 用户咨询机器人

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述 备注
partnerid String 是 企业自己的用户id，可自行传值
question String 是 用户问题 示例参照表格下方详解
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时，示例参照表格下方详解
msg_type Integer 否 消息类型 0：文本,1：图片,3：视频,4：文件，默认0，表情属于文本
lan_flag Integer 否 语言标识 不传则使用渠道默认或用户来源渠道接待方案中语言，0：中文（简体），1：英文，2：中文（繁体），3：阿拉伯语，4：法语，5：葡萄牙语，6：韩语，7：西班牙语，8：意大利语，9：日语，10：德语，11：马来西亚语，12：印尼语，13：俄语，14：泰语，15：越南语，16：土耳其语
channel_flag String 否 子渠道id 根据对接渠道设置中的channelid传入
reception_version Integer 否 接待版本 0：v1旧版，1：v6新版，默认0。如果传入的是V6版本（1），但是公司实际最高配置是V1版本（0）则不会生效，只按照V1设置版本。

question 参数详解:

单轮：传入用户问题

多轮：需要根据上轮返回值中 multiDiaRespInfo 字段确定传入内容。

multiDiaRespInfo 中关键字段为：interfaceList 和 inputContentList，同一轮返回值中两者只会存在一个

1）如果上轮返回 interfaceList,只保留 template 和 interfaceRetList 的 json，其中 interfaceRetList 集合只保留选中的集合元素，例如：

		{
					"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":"01元",
							"title":"变形金刚III"
						},
						{
							"summary":"优秀电影",
							"thumbnail":"https://ilw.aliimg.com/media/lADODuM9KM0E2s0E1w_1239_12jpg",
							"anchor":"http://www.sina.com",
							"movieId":"3",
							"tag":"未上映",
							"label":"00",
							"title":"猩球崛起"
						}
					],
					"outPutParamList":"title#movieId"
				}
			客户选中title为"变形金刚III"的选项，则传入数据为：{
					"template":0,					
					"interfaceRetList":[
						{
							"summary":"好看的电影，不要错过",
							"thumbnail":"",
							"anchor":"http://www.baidu.com",
							"movieId":"1",
							"tag":"2020年上映",
							"label":"01元",
							"title":"变形金刚III"
						}
					]
				}
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
40
41
42
43
44
45
46
47
48

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

{
	"template":0,
	"question":"我想买手机",
	"level":0,
	"conversationId":"a4bb45ed-594e-4953-b74e-e2f91337f",
	"docId":"022e96da2f8346b7bfb0efb400a9c558",
	"groupId":"9a38730078354d4a832a6c621483ad9d",
	"remindQuestion":"请选择品牌",
	"endFlag":false,
	"levelName":"品牌",
	"retCode":"000000",
	"inputContentList":"华为,苹果,小米",
	"outPutParamList":"品牌"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

选中 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":"01元",
			"title":"变形金刚III"
		},
		{
			"summary":"优秀电影",
			"thumbnail":"https://ilw.lmg.com/media/12jpg",
			"anchor":"http://www.sina.com",
			"movieId":"3",
			"tag":"未上映",
			"label":"00",
			"title":"猩球崛起"
		}
	],
	"outPutParamList":"title#movieId"
}
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

客户选中 title 为"变形金刚III"的选项，则传入数据为：

{
	"level":0,
	"conversationId":"5fcb4cb5-2078-41c7-bb9d-8f464c94",				
	"movieId":"1",
	"title":"变形金刚III"
}
1
2
3
4
5
6

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

{
	"template":0,
	"question":"我想买手机",
	"level":0,
	"conversationId":"a4bb45ed-594e-437f",
	"docId":"022e96da2f8346b7bfb0efb400a9c558",
	"groupId":"9a38730078354d4a832a6c621483ad9d",
	"remindQuestion":"请选择品牌",
	"endFlag":false,
	"levelName":"品牌",
	"retCode":"000000",
	"inputContentList":"华为,苹果,小米",
	"outPutParamList":"品牌"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

选中 inputContentList 里的华为，则传入数据为：

{
	"level":0,
	"conversationId":"a4bb45ed-594e-4953-b74e-e2f1337f",
	"品牌":"华为"
}
1
2
3
4
5

返回参数：

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

item 对象：

参数 类型 必填 描述
answer String 答案
answers List 多消息，由此字段，则answer为空，20220901新增
suggestions List 推荐问题列表，详见下文
question String 原始问题 词条名称
docid String 词条 id
visitorid String 用户 id
cid String 会话 id
msgid String 消息体 id,answer不为空时此字段有值
stripe String 问题推荐引导语
robot_flag String 机器人编号
answer_type String 机器人回答类型
gpt_answer_type String 否 思涌AI回答类型，1-直接回答
session_new String 是否是新会话
transfer_type String 触发转人工类型 0:不触发，1:重复提问，2:负向情绪，3:命中关键字，4-命中多轮规则，5-机器人自动，11-多轮节点转人工
transfer_flag String 否 多轮节点转人工模式：0-按客户分配策略，1-指定客服，2-指定技能组
transfer_targetid String 否 多轮节点转人工目标id：客服或技能组id
multi_response_info Object 多轮会话返回数据
answerid String 答案Id，answer不为空时此字段有值，20220901新增
ruleid String 规则Id，20220901新增
kbid String 知识库Id，20220901新增
kb_name String 知识库名称，20220901新增
special_msg_flag Integer 机器人特殊消息(图片、视频、文件、表情)命中标识 0没有命中 1标识命中，20250415新增

answers对象：

参数 类型 必填 描述
answerid String 答案Id
msgid String 消息Id
answer String 答案， 只支持返回固定未知说辞：“为了更好的解决您的问题，请用文字描述您的问题。”

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

返回示例：

{
    "item":{
        "answer":"xx",
        "answers":[
            {
                "answer":"xx",
                "answerid":"xx",
                "msgid":"xxx"
            }
        ],
        "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",
        "answerid":"xxx",
        "ruleid":"xxx",
        "kbid":"xxx",
        "kb_name":"xxx",
        "special_msg_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
26
27
28
29
30
31
32
33
34
35
36
# ● 用户输入调取分词联想

接口说明：

接口类型：主动调用接口

接口作用：可通过调用该接口获取对应知识库中输入问题的分词联想结果

请求方式：

POST

请求地址：

 https://www.sobot.com/api/chat/5/user/query_suggest
1

请求参数：

参数 类型 必填 描述 备注
partnerid String 是 企业自己的用户id，可自行传值
question String 是 用户问题 用户搜索分词联想的问题
robot_flag String 否 机器人编号 默认:1
num Integer 否 联想词条个数

返回参数：

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

item 对象：

参数 类型 必填 描述
originQuestion String 查询所用原问题
respInfoList List 分词联想结果数组,详见下文

respInfoList对象：

参数 类型 必填 描述
docId String 分词联想问题的词条 Id
questionId String 分词联想的问题id
question String 分词联想问题的名称
highlight String 展示及高亮分词联想问题

请求示例：

curl https://www.sobot.com/api/chat/5/user/query_suggest \
-X POST \
-H 'token:056b5b979ff54753869e3deef6a657d6' \
-F 'partnerid=xx' \
-F 'question=删除' \
-F 'num=5' \
-F 'robot_flag=1'
1
2
3
4
5
6
7

返回示例：

{
    "respInfoList": [
        {
            "questionId": "2939578d354d4850a3d7b789dcb54caa",
            "question": "删除??",
            "docId": "07a917c9b6734f65a1145a80a84e5e3f",
            "highlight": "<font color='red'>删除</font>??"
        }
    ],
    "originQuestion": "删除"
}
1
2
3
4
5
6
7
8
9
10
11
# ● 机器人回答评价

接口说明：

接口类型：主动调用接口

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

请求方式：

POST

请求地址：

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

请求参数：

参数 类型 必填 描述
visitorid String 是 访客 id
cid String 是 会话 id
docid String 是 词条 id
doc_name String 是 词条名称
robot_flag String 是 机器人 id
status String 是 评价状态
msgid String 是 消息 id，若机器人咨询接口的answers有值，则传answers中的msgid
partnerid String 否 企业自己的用户 id，可自行传值
from String 否 客户来源
answerid String 否 单轮问题可不传
ruleid String 否 规则答案必传
answer String 否 多轮必传

注：如没有 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"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14

返回示例：

{
    "item": {
        "ustatus": "-1"
    },
    "ret_code": "000000",
    "ret_msg": "成功"
}
1
2
3
4
5
6
7

# 单轮会话接口调用

# ● 单轮应用场景

智齿客服机器人除了可以进行基于知识库内容的问答外，还能够进行基于第三方接口的信息调用。

比如快递公司希望用户可以在与机器人沟通时自助查询快递情况，就可以针对此场景在知识库中设立一个机器人调用快递查询接口的问题。

当用户交互时若触发该问题，机器人就可以将用户希望查询的快递单号传递给查询接口，再将查询接口返回的信息发送给用户，实现用户的自助查询。

比如，用户输入订单查询：12345678，机器人就会调用订单查询接口，并将用户信息以及用户输入的订单号 12345678 传递给查询接口，若查询接口正常返回了查询结果，机器人将会把查询结果展示给用户。

# ● 如何设置

设置项说明：

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

11

其中各设置项的含义如下：

标准问法：用户输入中触发接口查询的关键字。该关键字必须在一次输入的开头。

比如，设置标准问法为订单查询，则订单查询：12345 可以正确触发接口调用，能不能订单查询将不会触发接口调用。接口调用问法的匹配优先级会高于其他问法，为关键字匹配，但为了避免造成知识库维护的混乱，请尽量避免与其他问题的标准问法一致或有包含关系。

接口 URL：调用接口的地址

http://www.test.com/Order
1

参数：需要机器人从用户输入内容中抽取的参数，并在调用接口时进行传递。

参数名称：传递该参数时使用的参数名，比如，OrderID，机器人在调用接口时将给 OrderID 参数赋值，并进行传递。

长度限制：限制此参数的长度，若用户输入的参数超过此长度，机器人将向用户展示调用说明。

参数说明：对此参数的备注说明信息。机器人不会使用此信息。

分隔符：与前一个参数或标准问法关键字区分开的符号，可以设置为空格、冒号、逗号、下划线、括号等。

12

token：调用接口时传递的 token，可随机生成，也可自定义。可作为智齿客服机器人在调用接口时的身份认证。

调用说明：当用户触发了接口调用，但未正确输入需要的参数时，机器人将把此处设定的内容展示给用户。

超时说明：在调用接口时若返回错误信息或超时，机器人将把此处设定的内容展示给用户。

选择分类：该问题在知识库中的分类。

生效时间：该问题的生效时间。

启用状态：该问题的启用状态。

设置示例：

标准问法：天气查询

接口 URL：

http://www.test.com/weather/query?
1

添加参数：

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

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

触发调用说明：

对于上例，用户在输入不同内容时的情况说明。

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

参数传递：

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

固定参数：

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

自定义参数：

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

# ● 接口返回格式

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

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

接口返回数据示例：

{
    "ret_code": 0,
    "ret_message": "今天是星期三，农历二月初四，现在温度为：5℃，湿度为：12，风向为：北风，风力为：3 级。"   
}
1
2
3
4
# ● 其他注意事项

接口调用超时时长：

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

编码格式：

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

返回答案长度：

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

# 多轮会话接口调用

# ● 多轮应用场景

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

1.仅获取变量

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

1

2.获取消息内容

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

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

2

# ● 模板样式和参数概览

1.模板一

3

4

2.模板二

5

6

3.模板三

7

4.模板四

8

5.自定义模板

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

6.不选模板

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

# ● 接口配置

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

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

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

9

# ● 请求参数

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

字段名称 字段说明 类型
partnerId 会话开始时，您传入智齿的客户的对接ID。未传则为空 固定参数
multiParams 会话开始时，您传入的multiParams参数，json键值对格式，如：{"city":"北京","category":"衬衫"}。未传则为空 固定参数
source 会话渠道。0为桌面网站（PC），2为APP，4为移动网站（H5） 固定参数
robotNo 调用接口的机器人ID，详见机器人信息中的robotId 固定参数
docId 调用本接口的问题ID 固定参数
自定义参数 您自定义的请求参数。值来源于多轮问题的具体配置 自定义参数

# (opens new window)请求示例

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//请求参数部分，分为固定参数和后台自定义参数两部分
1
2
3
4
5
6
# ● 返回参数

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

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

1.1 返回示例-正常情况

"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": "点击跳转地址"
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

1.2 返回示例-异常情况

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

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

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

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

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

{
    "code": "000000 '000000代表成功'",
    "list": [
        {
            "title": "北京",
            "cityId": "1" //城市 ID 
        },
        {
            "title": "上海",
            "cityId": "2" //城市 ID 
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

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

10

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

11

添加接口节点分支，当选择「城市」变量等于「北京」时，「获取电影院接口」会以 cityId = 1 去请求可选的影院。

12

# 错误编码

错误编码 错误说明
000000 操作成功（除此编码以外的编码为错误编码）
220001 [x] 的长度超过最大限制,最多允许 x 个字符
220006 [x] 参数类型错误
上次更新: 2025/4/2 20:19:09

← 知识库 API→

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