修改规则标签
概述
调用接口,可修改当前租户草稿机器人下的自定义规则标签(V2),包括标签名称、备注和子规则。修改成功后返回标签及子规则的最新配置和配置版本号。
本接口不修改父标签的启用状态,启用、禁用使用专用接口。父标签和对应子规则均启用时,该子规则才参与匹配;同一标签下多条启用子规则中,任意一条满足即可命中该标签。
URL
https://aiob-open.baidu.com/api/v1/robot/label/rule/update
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" |
| id | 是 | String | 待修改的标签 ID,从创建、列表或详情接口返回中取得。不是子规则 ID。 | "22222222-2222-4222-8222-222222222222" |
| name | 是 | String | 修改后的完整标签名称,须为非空白内容,最多 50 个字符。不改名也须传原名称;不能与同一机器人下其他未删除标签重名。 | "通话时长达标" |
| remark | 否 | String | 修改后的完整备注,最多 200 个字符。不传或传 null 会清空原备注,也可传空字符串;保留原备注时须显式带回原值。 | "通话时长不少于60秒" |
| version | 是 | int | 标签当前配置版本号,为非负整数。从查询结果中原样带回,不自行递增;与子规则版本号分别使用,不是机器人发布版本。 | 7 |
| rules | 否 | array<object> |
子规则列表。不传或传 null 保留原子规则;传 [] 清空全部子规则;传非空数组时按该数组全量同步,未包含的旧子规则会被删除。每个元素的参数见下表。 | 见请求示例 |
父标签 status 须省略或传 null,传 0 或 1 也会校验失败。需要改变父标签启用状态时,使用对应的启用、禁用接口。
子规则对象参数(rules 中的每个元素):
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| id | 修改已有子规则时必填 | String | 已有子规则的 ID,须属于本次修改的标签,同一请求中不能重复。新建子规则时省略或传 null,由服务端生成。 | "33333333-3333-4333-8333-333333333333" |
| version | 修改已有子规则时必填 | int | 该子规则当前配置版本号,为非负整数,按查询结果原样带回。新建子规则时须省略或传 null,不能传 0 代替省略。 | 3 |
| status | 否 | int | 本条子规则的启用状态:0 禁用,1 启用。不传或传 null 时按 1 保存,包括修改已有子规则;保留禁用状态时须显式传 0。 | 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 所属租户确定。机器人或标签不存在、已删除、不属于当前租户,或机器人不是草稿时,修改失败;标签须属于传入的 robotId。
- 只修改标签名称或备注时,可省略 rules 或传 null。只修改其中一条子规则时,rules 中也须完整带上其他需要保留的子规则及各自的 id、version、status 和 labelRuleVO,不能只提交有变化的子规则。
- 提交 rules 时,每个元素须为非 null 的规则对象;已有子规则须属于当前标签。修改后的列表最多包含 5 条启用子规则,不传或传 null 的子规则 status 按 1 计数,父标签禁用时也须满足该上限。
- 标签每次修改成功后 version 加 1;提交数组中的已有子规则,即使条件未变化,保存成功后各自的 version 也加 1。新建子规则的 version 初始为 0;rules 不传或传 null 时,原子规则版本不变。
- 遇到标签或子规则版本冲突时,重新查询最新配置,确认需要保留的内容后再提交,不自行递增版本号或直接重发旧请求。本次名称、备注和子规则修改在同一事务中完成,版本冲突或子规则校验失败时不会只保存其中一部分。
- 本接口只保存指定草稿的规则标签,不执行机器人发布;如需将草稿配置发布到线上,请使用现有发布流程。
响应参数
公共响应字段:
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| 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 | 本次修改后的标签配置版本号。下次修改时使用该值;不是机器人发布版本。 |
| rules | array<object> |
本次修改后完整的子规则列表,清空后为空数组。rules 不传或传 null 时返回原有子规则。每个子规则的字段见下表。 |
子规则对象字段(rules 中的每个元素):
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| id | string | 子规则 ID。新建子规则由服务端生成 ID,已有子规则沿用原 ID。 |
| status | int | 本条子规则实际启用状态:0 禁用,1 启用。 |
| version | int | 子规则当前配置版本号。更新的已有子规则加 1,新建子规则为 0;与父标签的 version 分别使用。 |
| labelRuleVO | object | 本条子规则已保存的匹配条件,结构见本页请求参数中的 labelRuleVO 及条件对象定义。未配置的条件字段可能为空。 |
调用方保留本次请求中的 robotId。后续修改时按本页请求结构组装参数,不能将整个 data 对象原样提交;父标签 status 须省略或传 null。
请求示例
1POST https://aiob-open.baidu.com/api/v1/robot/label/rule/update
1{
2 "robotId": "11111111-1111-4111-8111-111111111111",
3 "id": "22222222-2222-4222-8222-222222222222",
4 "name": "通话时长达标",
5 "remark": "通话时长不少于60秒",
6 "version": 7,
7 "rules": [
8 {
9 "id": "33333333-3333-4333-8333-333333333333",
10 "version": 3,
11 "status": 1,
12 "labelRuleVO": {
13 "relation": "AND",
14 "durationExpress": {
15 "operator": "GTE",
16 "compareValue": 60
17 }
18 }
19 },
20 {
21 "status": 0,
22 "labelRuleVO": {
23 "relation": "AND",
24 "artificialExpress": {
25 "operator": "EQUALS",
26 "compareValue": 1
27 }
28 }
29 }
30 ]
31}
本例假设父标签已启用且原来只有一条子规则,查询得到标签 version=7、该子规则 version=3。本次将通话时长条件改为不少于 60 秒,并新增一条禁用的“转人工成功”子规则。所有资源 ID、版本号及请求头中的 your_token 均须替换为实际值;如原来还有其他需要保留的子规则,也须一并放入 rules。
返回示例
以下示例对应上面的请求:父标签保持启用,标签 version 变为 8,已有子规则 version 变为 4,新建子规则 version 为 0。子规则返回顺序不作为请求顺序的保证,调用方按 id 对应。条件对象仅展示已保存的主要业务字段。
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": "通话时长不少于60秒",
10 "status": 1,
11 "version": 8,
12 "rules": [
13 {
14 "id": "44444444-4444-4444-8444-444444444444",
15 "status": 0,
16 "version": 0,
17 "labelRuleVO": {
18 "relation": "AND",
19 "artificialExpress": {
20 "operator": "EQUALS",
21 "compareValue": 1
22 }
23 }
24 },
25 {
26 "id": "33333333-3333-4333-8333-333333333333",
27 "status": 1,
28 "version": 4,
29 "labelRuleVO": {
30 "relation": "AND",
31 "durationExpress": {
32 "operator": "GTE",
33 "compareValue": 60
34 }
35 }
36 }
37 ]
38 }
39}
评价此篇文章
