任务 API

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

基础 URL — https://api.youraiconnector.com/v1
身份验证 — 您的 API 密钥（请参阅身份验证）
错误与分页 — 请参阅错误与分页

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

任务对象

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

创建任务

POST /tasks — 仅 title 为必填项。

注意： 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

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

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

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)

{ "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

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

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

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)

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

搜索任务

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

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

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" }),
});

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}

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

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

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）。

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." }'

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." }),
});

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 字段用于记录结束备注。

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." }'

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." }),
});

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（该阶段内从零开始的槽位；必填，必须为非负整数）：

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：

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"] }'

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"] }),
});

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} — 与特定联系人关联的所有任务。

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

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

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 字段。

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

{ "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 数组。

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 字段）。

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 代理发出。

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 }'

{ "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 以管理生成的 FAQ。

删除任务

DELETE /tasks/{taskId}

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

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

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

后续步骤

联系人 API — 将任务链接到正确的联系人
Webhooks API — 获取关于 Task Created、Task Updated 和 Task Completed 的通知
API 参考 — 完整的交互式端点浏览器

任务 API #

任务对象 #

创建任务 #

列出任务 #

搜索任务 #

获取任务 #

更新任务 #

完成任务 #

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

联系人的任务 #

任务看板配置 #

列出任务阶段 #

更新任务阶段 #

列出任务类型 #

批准 FAQ 建议 #

删除任务 #

后续步骤 #

任务 API

任务对象

创建任务

列出任务

搜索任务

获取任务

更新任务

完成任务

移动与重新排序（看板）

联系人的任务

任务看板配置

列出任务阶段

更新任务阶段

列出任务类型

批准 FAQ 建议

删除任务

后续步骤