创建规则标签
概述
调用接口,可在当前租户的草稿机器人下创建自定义规则标签(V2),并按需同时配置多条子规则。创建成功后返回标签及子规则的 ID、配置版本号和已保存配置。
父标签默认禁用,子规则默认启用;只有父标签和对应子规则均启用时,该子规则才参与匹配。同一标签下多条启用子规则中,任意一条满足即可命中该标签。
URL
https://aiob-open.baidu.com/api/v1/robot/label/rule/create
HTTP Method
POST
请求参数
HEADER
| 参数名称 | 是否必须 | 说明 | 示例 |
|---|---|---|---|
| Authorization | 是 | 参考“生成认证Token”文档获取完整的 OpenAPI Token,原样传入,不加 Bearer 前缀。 | cc-api-auth-v2/your_token |
| Content-Type | 是 | 请求体采用 JSON 格式。 | application/json |
PARAM
以下参数通过 JSON 请求体传入。
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| robotId | 是 | String | 当前租户的草稿机器人 ID,不能为空。线上机器人 ID 不会自动转换为草稿 ID。 | "11111111-1111-4111-8111-111111111111" |
| name | 是 | String | 标签名称,须为非空白内容,最多 50 个字符。同一机器人下未删除的标签不能重名。 | "通话时长达标" |
| remark | 否 | String | 标签备注,最多 200 个字符。可省略、传 null 或空字符串。 | "通话时长不少于30秒" |
| status | 否 | int | 父标签启用状态:0 禁用,1 启用。不传或传 null 时默认为 0。 | 1 |
| rules | 否 | array<object> |
子规则列表。不传、传 null 或 [] 时只创建空标签。每个元素的参数见下表。 | 见请求示例 |
子规则对象参数(rules 中的每个元素):
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| status | 否 | int | 本条子规则的启用状态:0 禁用,1 启用。不传或传 null 时默认为 1。 | 1 |
| labelRuleVO | 提交子规则时必填 | object | 本条子规则的匹配条件,不能为空,须包含 relation 和至少一种有效条件。字段见下表。 | 见下方条件定义 |
labelRuleVO 参数:
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| relation | 是 | String | 本条子规则内各条件的组合关系,仅支持 AND、OR,区分大小写。AND 表示全部满足,OR 表示任一满足。 | "AND" |
| durationExpress | 否 | object | 通话时长条件,单位为秒。比较值为非负 int,范围 0~2147483647。 | {"operator":"GTE","compareValue":30} |
| talkingTurnExpress | 否 | object | 机器人回复次数条件。比较值使用非负十进制整数字符串,范围 0~2147483647。 | {"operator":"BETWEEN","compareValue":"2","compareValueMax":"5"} |
| voiceTalkingTurnExpress | 否 | object | 用户回复次数条件。比较值类型及范围同 talkingTurnExpress。 | {"operator":"GTE","compareValue":"2"} |
| callTimesExpress | 否 | object | 拨打次数条件。比较值使用非负十进制整数字符串,范围 0~9223372036854775807。 | {"operator":"GTE","compareValue":"1"} |
| connectedTimesExpress | 否 | object | 接通次数条件。比较值使用非负十进制整数字符串,范围 0~2147483647。 | {"operator":"GTE","compareValue":"1"} |
| callStatusExpress | 否 | object | 接听状态条件。比较值为整数:0 未接听,1 已接听。 | {"operator":"EQUALS","compareValue":1} |
| callStatusDetailExpress | 否 | object | 最终通话状态条件,compareValues 为非空状态编码数组。可使用 answered(已接听)及当前“外呼记录筛选”可选原因编码,如 linebusy(用户忙)、nooneheard(无人接听);不要填写中文描述或数字分类值。 | {"operator":"IN","compareValues":["answered"]} |
| hangupExpress | 否 | object | 挂断方条件。比较值为整数:0 机器人挂断,1 管理员挂断,2 用户挂断,3 振铃挂断。 | {"operator":"EQUALS","compareValue":2} |
| artificialExpress | 否 | object | 转人工结果条件。比较值为整数:0 未发起,1 成功,-1 失败。 | {"operator":"EQUALS","compareValue":1} |
| collectInfoExpresses | 否 | array<object> |
采集内容匹配条件。每项按采集内容与自定义变量合并后的值匹配,不按字段名区分。 | [{"operator":"IN","compareValues":["已购"]}] |
| modelLabelExpresses | 否 | array<object> |
模型标签匹配条件,compareValues 按“标签名:标签值”填写,例如“意向:高”;仅填标签值(如“高”)不会正确匹配。 | [{"operator":"IN","compareValues":["意向:高"]}] |
除 relation 外,至少填写一种有效条件。未使用的条件可省略或传 null;采集、模型条件的空数组不算有效条件。即使父标签或子规则为禁用状态,提交的子规则也须通过完整条件校验。
条件对象参数(上表各条件对象及数组中的每个条件对象):
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| operator | 是 | String | 比较方式,区分大小写。不同条件允许的取值见下表。 | "GTE" |
| compareValue | 单值条件必填 | int 或 String | 单值比较的目标值;BETWEEN 时为区间下界。类型、范围或枚举值见对应条件说明。 | 30 或 "2" |
| compareValueMax | BETWEEN 时必填 | int 或 String | 区间上界,类型与 compareValue 一致,上界不能小于下界。BETWEEN 包含上下界。其他比较方式可省略。 | "5" |
| compareValues | 多值条件必填 | array<string> |
最终通话状态、采集内容和模型标签条件使用的比较值列表。采集、模型条件每个对象须有 1~10 个比较值,每个值须为非空白字符串且最多 100 个字符;最终通话状态按其有效状态编码校验。 | ["answered"] |
各类条件允许的比较方式:
| 条件类型 | operator 取值 | 说明 |
|---|---|---|
| 通话时长、机器人和用户回复次数、拨打及接通次数 | EQUALS、GT、GTE、LT、LTE、BETWEEN | 分别表示等于、大于、大于等于、小于、小于等于、包含两端的区间。数值须为非负整数。 |
| 接听状态、挂断方 | EQUALS、GT、GTE、LT、LTE | 按各自的合法整数枚举比较,通常使用 EQUALS。 |
| 转人工结果 | EQUALS | 仅支持等于比较。 |
| 最终通话状态、采集内容、模型标签 | IN、NOT_IN | 对参与比较的实际值,IN 表示命中任一候选项,NOT_IN 表示未命中任何候选项;候选项通过 compareValues 提交。 |
使用 IN 时,同一个 compareValues 数组中的多个值是“任一命中”的候选项,不会因 relation=AND 而要求全部命中。若要同时满足多个采集值或模型标签条件,应分别配置条件对象,再将单条子规则的 relation 设为 AND。
当前多值匹配会把单个比较文本或实际值里的英文逗号也作为分隔符。拆分后按完整项、区分大小写比较,不做子串模糊匹配。
说明:
- 创建范围由 Authorization 所属租户确定。机器人不存在、已删除、不属于当前租户或不是草稿时,创建失败。
- 每个标签最多 5 条启用子规则,按子规则 status=1 计数;未传子规则 status 时按 1 计数。父标签禁用时也须满足该上限。
- rules 数组的每一项须为规则对象,不能为 null。新建标签及新建子规则的 id、version 由服务端生成,创建请求不要填写这些字段。
- 创建空标签时,返回的 rules 为空数组。只有启用的标签下存在满足条件的启用子规则时,标签才会命中。
- 本接口只保存指定草稿的规则标签,不执行机器人发布;如需将草稿配置发布到线上,请使用现有发布流程。
- 保存创建成功返回的标签 id 和本次请求的 robotId,后续查询、修改、启停或删除时使用。如果调用超时、结果不确定,先查询该机器人下同名标签是否已创建,再决定是否重试。
响应参数
公共响应字段:
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| requestId | string | 请求标识,用于定位请求。 |
| time | long | 响应时间戳,单位为毫秒。 |
| code | int | 业务结果码,200 表示成功。 |
| msg | string | 处理结果说明。 |
| data | object | 本次创建的规则标签及其已保存配置,字段见下表。 |
data 字段(标签对象):
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| id | string | 服务端生成的标签 ID,后续操作该标签时使用。 |
| name | string | 实际保存的标签名称。 |
| remark | string | 标签备注,可能为空。 |
| status | int | 父标签实际启用状态:0 禁用,1 启用。创建后启停使用专用接口操作。 |
| version | int | 标签配置版本号,创建时初始值为 0。后续修改标签时原样带回,用于并发校验;不是机器人发布版本。 |
| rules | array<object> |
已创建的子规则列表,未创建子规则时为空数组。每个子规则的字段见下表。 |
子规则对象字段(rules 中的每个元素):
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| id | string | 服务端生成的子规则 ID,修改已有子规则时使用。 |
| status | int | 本条子规则实际启用状态:0 禁用,1 启用。 |
| version | int | 子规则配置版本号,创建时初始值为 0;与父标签的 version 分别使用。 |
| labelRuleVO | object | 本条子规则已保存的匹配条件,结构见本页请求参数中的 labelRuleVO 及条件对象定义。未配置的条件字段可能为空。 |
后续修改时需按修改接口组装请求,不能将整个 data 对象原样提交。标签和已有子规则分别带回各自的 id、version,不自行递增版本号;修改接口中的父标签 status 需省略或传 null,启停使用专用接口。
请求示例
1POST https://aiob-open.baidu.com/api/v1/robot/label/rule/create
1{
2 "robotId": "11111111-1111-4111-8111-111111111111",
3 "name": "通话时长达标",
4 "remark": "通话时长不少于30秒",
5 "status": 1,
6 "rules": [
7 {
8 "status": 1,
9 "labelRuleVO": {
10 "relation": "AND",
11 "durationExpress": {
12 "operator": "GTE",
13 "compareValue": 30
14 }
15 }
16 }
17 ]
18}
示例显式启用父标签和子规则,匹配条件为“通话时长不少于 30 秒”。robotId 需替换为当前租户的实际草稿机器人 ID,name 需保证在该机器人下不重名。请求头中的 your_token 需替换为实际 Token。
返回示例
条件对象仅展示已保存的主要业务字段。
1{
2 "requestId": "example-request-id",
3 "time": 1794787200000,
4 "code": 200,
5 "msg": "OK",
6 "data": {
7 "id": "22222222-2222-4222-8222-222222222222",
8 "name": "通话时长达标",
9 "remark": "通话时长不少于30秒",
10 "status": 1,
11 "version": 0,
12 "rules": [
13 {
14 "id": "33333333-3333-4333-8333-333333333333",
15 "status": 1,
16 "version": 0,
17 "labelRuleVO": {
18 "relation": "AND",
19 "durationExpress": {
20 "operator": "GTE",
21 "compareValue": 30
22 }
23 }
24 }
25 ]
26 }
27}
评价此篇文章
