---
pageClass: semantic-callouts
---

# 客户导入

该接口用于导入客户到任务中并开始进行外呼。使用该接口前需要先在系统中创建任务，再根据查询任务列表获取到任务ID。

<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/import`

## 请求头

 <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;">taskId</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

任务ID，指定客户导入到对应的任务，该ID可以从获取任务列表接口中获取

---

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

需要导入的客户列表，每次最大值为2000条，客户列表数据，结构如下：

<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;">phoneNumber</span> `string` <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

客户联系方式，同一个任务中不允许存在重复号码，如果导入重复号码，后面的号码会被直接忽略，可以为标准手机号码，也支持固话，支持以下格式固话：

<div style="margin-left: 20px;">

- `(010)xxxxxxxx` 括号是英文半角括号
- `010-xxxxxxxx`
- `010xxxxxxxx`

</div>

---

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

随路数据，当机器人中配置了变量时，可以通过该参数关联变量和客户，格式为 `{"变量名": "值"}`，该值可以在通话记录回调时回传回去。除关联变量外，该字段也常用于携带您系统中的客户唯一标识，以便回调时匹配客户，详见下方提示。

</div>

</details>

::: tip 如何将回调的通话记录匹配到您系统中的客户？
通话记录回调数据中不包含您系统中的客户信息，且同一手机号可能被导入到多个任务或多次导入，直接使用手机号匹配容易产生歧义。

建议在导入客户时，通过 `ext` 字段传入该客户在您系统中的唯一标识，例如：

```json
"ext": { "id": "10001" }
```

该客户外呼结束后，其每一次通话记录回调都会**原样携带**这份 `ext` 数据，您可以据此将通话记录精确关联到您系统中的客户。详见[《通话记录回调数据格式说明》](https://avavox.com/docs/developer/call-record.html)中的 `ext` 字段。
:::




## 调用建议

本接口适用于批量数据导入场景，不建议用于高频实时逐条写入场景。

**推荐做法**

将待导入的客户数据在本地聚合后，以一次请求批量提交（每次最多 2000 条）。例如每隔数秒收集一批数据后统一导入。

如果每次仅导入少量数据（如每次仅 1 条）并高频调用，可能导致数据处理延迟显著增加，后提交的数据需要较长时间才能被处理。

::: warning 限流提示
为保障平台稳定性，系统可能对异常高频调用进行限流处理。
:::


## 响应数据


 <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; ">requestId</span> <code style="background:#f0f0f0; ">string</code>

导入操作的ID

</div>
</details>

::: tip 异步处理说明
本接口为异步导入，响应中的 `requestId` 仅表示导入请求已受理，并不代表客户数据已全部处理完成。每条客户数据的最终导入结果（成功 / 失败及失败原因）会通过回调推送，详见 [《导入结果回调数据格式说明》](https://avavox.com/docs/developer/data-import-callback.html)。
:::



## 请求示例

```shell
curl -X POST --location 'https://dashboard.avavox.com/open/api/task/import' \
--header 'Authorization: Bearer $Key' \
--header 'Content-Type: application/json' \
--data '{
  "taskId": "xxx",
  "customers": [
    {
      "phoneNumber": "10086",
      "ext": {
        "客户姓名": "张三",
        "手机尾号": "0086"
      }
    }
  ]
}'

```



## 响应示例

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