# 任务 API

任务是附加到您账户的待办事项和后续跟进工作——可选择关联到联系人、交易或营销活动。它们会在您的任务看板（看板列）的**阶段**中移动，并具有**类型**和**优先级**。本指南涵盖了如何通过 API 管理这些任务。

- **基础 URL** — `https://api.youraiconnector.com/v1`
- **身份验证** — 您的 API 密钥（请参阅 [身份验证](authentication.md)）
- **错误与分页** — 请参阅 [错误与分页](errors-and-pagination.md)

以下所有示例均展示了 cURL 中的 `?apiKey=` 查询形式，以及 JavaScript 和 Python 中的 `X-API-Key` 标头——两者均适用于所有端点。

---

## 任务对象

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`、`faq_update` 或您配置的任务类型（请参阅 [列出任务类型](#list-task-types)）。
- **`priority`** — `none`、`low`、`normal`、`high` 或 `urgent`。
- **`stage`** — 任务看板上某个阶段的 ID（请参阅 [列出任务阶段](#list-task-stages)）。创建时如果省略，任务将进入您的第一个阶段。
- **`remind_before_minutes`** — 在 `due_date` 之前多少分钟发送提醒。`0` 表示在截止时间发送；省略它或发送 `null` 则表示不发送提醒。必须是 `0` 到 `1440`（1 天）之间的整数——超过此范围将被拒绝。提醒需要 `due_date` 才能触发，重新安排任务时间会同步移动提醒。

---

## 创建任务

`POST /tasks` — 仅 `title` 为必填项。

::: note
**注意：** `due_date` 接受 ISO 8601 时间戳，包括具体时间。将其与 `remind_before_minutes` 搭配使用，即可根据您的**任务**通知设置发送提醒。`contact_id`、`deal_id` 和 `campaign_id` 将任务关联到这些记录。`assigned_to` 是团队成员的用户 ID。
:::


> **正确设置 `assigned_to`。** 它应该是账户所有者或同一账户下活跃团队成员的用户 ID。此端点目前不会进行校验，因此即使是无效的 ID 也会被接受并按原样存储——你仍然会收到 `201`。请直接复制 ID 而不要手动输入：这些 ID 混合了 `l` 和 `L`，以及字母 `O` 和数字 `0`，输入错一个字符就会导致错误。若要检查你实际发送的内容，请在仪表板中打开该任务：当任务记录中的 **Assignee**（负责人）字段匹配不到任何人时，它会回退显示原始 ID，并且 **Edit task**（编辑任务）中的负责人选择器会显示 **Unassigned**（未分配）。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**响应** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## 列出任务

`GET /tasks` — 返回您账户的任务，支持可选筛选器。

**查询参数**（均为可选）：`stage`、`priority`、`contact_id`、`deal_id`、`assigned_to`、`due_before`、`due_after`（ISO 时间戳）。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**响应** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## 搜索任务

`POST /tasks/search` — 对标题和描述进行全文匹配，并支持与列表相同的可选过滤器。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});
```

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## 获取任务

`GET /tasks/{taskId}`

```bash
curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

如果任务在您的账户中不存在，则返回 `404`。

---

## 更新任务

`PUT /tasks/{taskId}` — 仅发送您想要更改的字段（`title`、`description`、`type`、`priority`、`stage`、`due_date`、`remind_before_minutes`、`contact_id`、`deal_id`、`assigned_to`、`tags`、`notes`）。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## 完成任务

`POST /tasks/{taskId}/complete` — 将任务移动到看板的“已完成”阶段。可选的 `notes` 字段用于记录结束备注。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## 移动与重新排序（看板）

**将任务移动到另一个阶段** — `POST /tasks/{taskId}/move`，包含 `new_stage_id`（目标阶段）和 `new_position`（该阶段内从零开始的槽位；必填，必须为非负整数）：

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**在阶段内对任务重新排序** — `POST /tasks/reorder`，包含 `stage_id` 以及按新顺序排列的任务 ID：

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## 联系人的任务

`GET /tasks/contact/{contactId}` — 与特定联系人关联的所有任务。

```bash
curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## 任务看板配置

### 列出任务阶段

`GET /tasks/stages` — 您看板的列，按顺序排列。在创建或移动任务时，使用阶段 `id` 作为 `stage` 字段。

```bash
curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"
```

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### 更新任务阶段

`PUT /tasks/stages` — 替换您看板的阶段配置。发送完整的有序 `stages` 数组。

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### 列出任务类型

`GET /tasks/types` — 您账户中配置的任务类型（用作 `type` 字段）。

```bash
curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"
```

---

## 批准 FAQ 建议

当 AI 机器人提出新的常见问题解答（FAQ）时，它会创建一个类型为 `faq_update` 的任务。`POST /tasks/{taskId}/approve-faq` 会将该建议转换为提出该建议的 AI 代理知识库中的真实 FAQ，并完成该任务。您可以在正文中覆盖问题/答案。

添加 `"send_follow_up": true` 还可以让 AI 立即将答案发送给任务关联的联系人，作为该聊天中的自然消息（这与应用程序中 **立即将答案发送给联系人** 开关的功能相同）。回复将通过处理该联系人的 AI 代理发出。

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status` 会告诉您消息的处理结果：`not_requested`（未设置标志）、`published`（已发送）、`queued`（机器人正在回复该联系人，答案将在回复完成后立即发出）、`skipped_no_contact`（任务没有关联的联系人）、`skipped_no_campaign`（没有代理或营销活动可以为该联系人提供答案）或 `skipped_error`。无论哪种情况，FAQ 都会被创建。

请参阅 [FAQs API](faqs.md) 以管理生成的 FAQ。

---

## 删除任务

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## 后续步骤

- [联系人 API](contacts.md) — 将任务链接到正确的联系人
- [Webhooks API](webhooks.md) — 获取关于 `Task Created`、`Task Updated` 和 `Task Completed` 的通知
- [API 参考](reference.md) — 完整的交互式端点浏览器