# 创建任务

该接口用于创建外呼任务。使用前需确保已在系统中完成以下准备工作：

- 已创建并发布好机器人
- 如需外呼功能，需预先配置线路

**说明**
- 创建任务后会返回任务ID
- 需要使用[「客户导入」](https://avavox.com/docs/developer/data-import.html)接口将客户添加到任务中
- 完成客户导入后，系统才能开始外呼

<span style="display:inline-block;background:#e6f8ea;color:#fca130;border-radius:6px;padding:2px 8px;font-weight:bold;font-family:monospace;margin-right:8px;">POST</span>
`https://dashboard.avavox.com/open/api/task`

## 请求头

 <span style="font-family:monospace; color:#3451b2; ">Authorization </span> <code style="background:#f0f0f0; ">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

- 填写格式：`Authorization: Bearer <App Key>`
- `<App Key>` 为控制台「App Key 管理」页面生成的 Key。
- 获取方式详见：[《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。


## 请求体参数

<span style="font-family:monospace; color:#3451b2;">taskName</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

任务名称，长度 1–300 个字符

---

<span style="font-family:monospace; color:#3451b2;">robotId</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

需要关联的机器人，可在机器人详情中获取，或通过[机器人查询](https://avavox.com/docs/developer/query-robot.html)接口获取

---

<span style="font-family:monospace; color:#3451b2;">clientBizId</span> `string` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

调用方业务ID，用于关联您系统中的业务数据，后续可通过该字段查询任务，长度 ≤128 个字符

---

<span style="font-family:monospace; color:#3451b2;">metadata</span> <code style="background:#f0f0f0;">object</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

随路数据，以键值对形式传入，创建成功后会随任务原样返回，序列化后的 JSON 字符串长度 ≤4000 个字符

---


<span style="font-family:monospace; color:#3451b2;">lineId</span> `string` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

需要使用的线路，可通过[线路查询](https://avavox.com/docs/developer/query-line.html)接口获取，为空时，任务不能进行外呼


---

<span style="font-family:monospace; color:#3451b2;">lineIds</span> `array` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

需要使用的线路列表，可通过[线路查询](https://avavox.com/docs/developer/query-line.html)接口获取。

- 仅传 `lineIds` 时，使用该列表作为任务线路配置
- 同时传 `lineId` 和 `lineIds` 时，系统会将两者合并后作为最终线路配置
- 若存在重复线路 ID，系统会自动去重

---


<span style="font-family:monospace; color:#3451b2;">backgroundAudio</span> `string` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

背景音。
- `office_ambient`：办公室环境音
- `busy_call_center`：繁忙的呼叫中心办公室
- `telemarketing_office`：电销办公室


---

<span style="font-family:monospace; color:#3451b2;">concurrency</span> `number` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

任务的最大并发呼叫数。不传则保持原配置。实际生效并发数为「任务配置的并发数」与「所用线路支持的最大并发数」两者中的较小值。


---


<span style="font-family:monospace; color:#3451b2;">runtimeConfig</span> `object` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

运行时配置项，用于控制任务的行为策略，包括重呼配置等。

<details>
<summary >点击展开字段说明</summary>
<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">

<span style="font-family:monospace; color:#3451b2;">retryConfig</span> `object` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

重呼配置，如果要禁用重呼配置，必须将 `enabled` 设置为 `false` 才会生效

<details>
<summary >点击展开字段说明</summary>
<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">


<span style="font-family:monospace; color:#3451b2;">retryableStatuses</span> `array` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

触发重呼的状态列表，可多选，枚举值如下：

- `unconnected`：未接通
- `no_one_answer`：无人接听
- `timeout`：超时未接听
- `user_refuse`：用户拒接
- `unreachable`：无法接通
- `insufficient_balance`：用户欠费
- `powered_off`：关机
- `service_suspended`：停机
- `invalid_number`：空号
- `call_fail`：呼叫失败
- `busy`：占线

---

<span style="font-family:monospace; color:#3451b2;">maxRetries</span> `number` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

重呼次数，最大为5次

---

<span style="font-family:monospace; color:#3451b2;">retryInterval</span> `number` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

呼叫间隔，最小为1，单位：分钟

---

<span style="font-family:monospace; color:#3451b2;">enabled</span> `boolean` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

是否启用重呼配置，`true`-启用，`false`-不启用，默认为 `true`

</div>

</details>


</div>

</details>

---


<span style="font-family:monospace; color:#3451b2;">callTimeType</span> `string` <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

拨打时间类型，默认为`immediate`，枚举值如下：

- `immediate`：立即拨打，创建任务并导入数据之后，立即开始拨打
- `scheduled`：根据选择的拨打时间段进行拨打

---


<span style="font-family:monospace; color:#3451b2;">scheduledTime</span> <code style="background:#f0f0f0;">array</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

定义任务的拨打时间。可定义多个时间段，各时间段之间不能交叉，仅当拨打时间类型（`callTimeType`）为 `scheduled` 时该字段才会生效。结构如下:


<details>
<summary >点击展开字段说明</summary>

<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">


<span style="font-family:monospace; color:#3451b2;">dayOfWeeks</span> `array` <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

时间片段生效的日期，周一到周天分别对应 1 到 7

---




<span style="font-family:monospace; color:#3451b2;">times</span> <code style="background:#f0f0f0;">array</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

可以拨打的时间段。每个时间段不能交叉，结构如下：

<details>
<summary >点击展开字段说明</summary>


<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">


<span style="font-family:monospace; color:#3451b2;">startTime</span> `string` <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

开始时间，时间格式为 `HH:mm`，精确到分钟

---

<span style="font-family:monospace; color:#3451b2;">endTime</span> `string` <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

结束时间，时间格式为 `HH:mm`，精确到分钟


</div>
</details>


</div>
</details>









## 响应数据


 <span style="font-family:monospace; color:#3451b2; ">code</span> <code style="background:#f0f0f0; ">int</code>

状态码，200 为成功，其他状态均为失败。

---

 <span style="font-family:monospace; color:#3451b2; ">success</span> <code style="background:#f0f0f0;">boolean</code>

是否成功，`true` 表示成功，`false` 表示失败。

---


 <span style="font-family:monospace; color:#3451b2; ">message</span> <code style="background:#f0f0f0; ">string</code>

描述信息

---

 <span style="font-family:monospace; color:#3451b2; ">data</span> <code style="background:#f0f0f0; ">object</code>

<details>
<summary >点击展开字段说明</summary>


<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">

<span style="font-family:monospace; color:#3451b2; ">taskId</span> <code style="background:#f0f0f0; ">string</code>

对应任务ID

</div>
</details>




## 请求示例

```shell
curl -X POST --location 'https://dashboard.avavox.com/open/api/task' \
--header 'Authorization: Bearer $Key' \
--header 'Content-Type: application/json' \
--data '{
  "taskName": "任务名称",
  "robotId": "关联的机器人ID",
  "clientBizId": "ORDER_20260722001",
  "metadata": {
    "orderId": "10001"
  },
  "lineId": "线路ID",
  "lineIds": ["线路ID1"],
  "backgroundAudio": "office_ambient",
  "concurrency": 1,
  "runtimeConfig": {
    "retryConfig": {
      "retryableStatuses": ["busy", "timeout"],
      "maxRetries": 1,
      "retryInterval": 1,
      "enabled": true
    }
  },
  
  "callTimeType": "scheduled",
  "scheduledTime": [
    {
      "dayOfWeeks": [
        1, 2, 3, 4, 5
      ],
      "times": [
        {
          "startTime": "09:00",
          "endTime": "12:00"
        },
        {
          "startTime": "14:00",
          "endTime": "18:00"
        }
      ]
    },
    {
      "dayOfWeeks": [
        6, 7
      ],
      "times": [
        {
          "startTime": "10:00",
          "endTime": "12:00"
        },
        {
          "startTime": "15:00",
          "endTime": "17:00"
        }
      ]
    }
  ]
}'

```



## 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "success": true,
  "data": {
    "taskId": "xxx"
  }
}
```