API Tác vụ

Tác vụ là các việc cần làm và theo dõi được đính kèm với tài khoản của bạn — có thể tùy chọn liên kết với một liên hệ, giao dịch hoặc chiến dịch. Chúng di chuyển qua các giai đoạn trên bảng tác vụ của bạn (các cột kanban của bạn) và có loại cũng như độ ưu tiên. Hướng dẫn này bao gồm cách quản lý chúng thông qua API.

URL cơ sở — https://api.youraiconnector.com/v1
Xác thực — khóa API của bạn (xem Xác thực)
Lỗi & phân trang — xem Lỗi & Phân trang

Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn ?apiKey= trong cURL và tiêu đề X-API-Key trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.

Đối tượng tác vụ

{
  "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, hoặc các loại tác vụ bạn đã cấu hình (xem Liệt kê các loại tác vụ).
priority — none, low, normal, high, hoặc urgent.
stage — id của một giai đoạn trên bảng tác vụ của bạn (xem Liệt kê các giai đoạn tác vụ). Khi bỏ qua lúc tạo, tác vụ sẽ nằm ở giai đoạn đầu tiên của bạn.
remind_before_minutes — số phút trước due_date để gửi lời nhắc. 0 nghĩa là đúng thời hạn; bỏ qua hoặc gửi null nếu không muốn nhắc nhở. Phải là một số nguyên từ 0 đến 1440 (1 ngày) — bất kỳ giá trị nào lớn hơn sẽ bị từ chối. Lời nhắc cần có due_date để kích hoạt, và việc lên lịch lại tác vụ sẽ di chuyển lời nhắc theo tác vụ đó.

Tạo tác vụ

POST /tasks — chỉ bắt buộc title.

Lưu ý: due_date chấp nhận dấu thời gian ISO 8601, bao gồm cả thời gian trong ngày. Hãy kết hợp nó với remind_before_minutes để nhận lời nhắc theo cài đặt thông báo Tác vụ của bạn. contact_id, deal_id, và campaign_id liên kết tác vụ với các bản ghi đó. assigned_to là id người dùng của một thành viên trong nhóm.

Thiết lập assigned_to chính xác. Đây phải là id người dùng của chủ tài khoản hoặc của một thành viên nhóm đang hoạt động trong cùng tài khoản đó. Điểm cuối này hiện không kiểm tra điều đó, vì vậy một id không thuộc về ai vẫn được chấp nhận và lưu trữ chính xác như những gì bạn đã gửi — bạn vẫn nhận được phản hồi 201. Hãy sao chép id thay vì nhập lại: các id này trộn lẫn l với L và chữ cái O với chữ số 0, và chỉ cần sai một ký tự là đủ. Để kiểm tra những gì bạn thực sự đã gửi, hãy mở tác vụ trong bảng điều khiển: trường Người được giao (Assignee) trên bản ghi tác vụ sẽ hiển thị id thô khi nó không khớp với bất kỳ ai, và bộ chọn người được giao trong Chỉnh sửa tác vụ (Edit task) sẽ hiển thị Chưa được giao (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"])

Phản hồi (201)

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

Liệt kê tác vụ

GET /tasks — trả về các tác vụ cho tài khoản của bạn, với các bộ lọc tùy chọn.

Các tham số truy vấn (tất cả đều tùy chọn): stage, priority, contact_id, deal_id, assigned_to, due_before, due_after (dấu thời gian 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"]

Phản hồi (200)

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

Tìm kiếm tác vụ

POST /tasks/search — khớp toàn văn bản trên tiêu đề và mô tả, với các bộ lọc tùy chọn tương tự như khi liệt kê.

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

Lấy một tác vụ

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

Một tác vụ không tồn tại trong tài khoản của bạn sẽ trả về 404.

Cập nhật một tác vụ

PUT /tasks/{taskId} — chỉ gửi các trường bạn muốn thay đổi (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."},
)

Hoàn thành một tác vụ

POST /tasks/{taskId}/complete — di chuyển tác vụ đến giai đoạn đã hoàn thành trên bảng của bạn. Một trường notes tùy chọn sẽ ghi lại ghi chú đóng tác vụ.

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

Di chuyển & sắp xếp lại (kanban)

Di chuyển một tác vụ sang giai đoạn khác — POST /tasks/{taskId}/move với new_stage_id (giai đoạn đích) và new_position (vị trí bắt đầu từ số 0 trong giai đoạn đó; bắt buộc, phải là một số nguyên không âm):

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

Sắp xếp lại các tác vụ trong một giai đoạn — POST /tasks/reorder với stage_id và các id tác vụ theo thứ tự mới:

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

Các tác vụ cho một liên hệ

GET /tasks/contact/{contactId} — mọi tác vụ được liên kết với một liên hệ.

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

Cấu hình bảng tác vụ

Liệt kê các giai đoạn tác vụ

GET /tasks/stages — các cột trên bảng của bạn, theo thứ tự. Sử dụng id của giai đoạn làm trường stage khi tạo hoặc di chuyển tác vụ.

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

Cập nhật các giai đoạn tác vụ

PUT /tasks/stages — thay thế cấu hình giai đoạn trên bảng của bạn. Gửi toàn bộ mảng stages đã được sắp xếp.

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

Liệt kê các loại tác vụ

GET /tasks/types — các loại tác vụ được cấu hình trên tài khoản của bạn (được sử dụng làm trường type).

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

Phê duyệt một đề xuất FAQ

Khi bot AI đề xuất một FAQ mới, nó sẽ tạo ra một tác vụ thuộc loại faq_update. POST /tasks/{taskId}/approve-faq biến đề xuất đó thành một FAQ thực sự trong cơ sở kiến thức của tác nhân AI đã đưa ra đề xuất đó và hoàn thành tác vụ. Bạn có thể ghi đè câu hỏi/câu trả lời trong phần nội dung.

Thêm "send_follow_up": true để AI cũng gửi ngay câu trả lời cho liên hệ được liên kết với tác vụ, dưới dạng một tin nhắn tự nhiên trong cuộc trò chuyện đó (tương tự như những gì nút gạt Gửi câu trả lời cho liên hệ ngay bây giờ thực hiện trong ứng dụng). Câu trả lời được gửi đi thông qua tác nhân AI xử lý liên hệ đó.

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 cho bạn biết điều gì đã xảy ra với tin nhắn: not_requested (cờ không được đặt), published (đã gửi), queued (bot đang trả lời dở dang cho liên hệ đó, câu trả lời sẽ được gửi đi ngay khi nó hoàn tất), skipped_no_contact (tác vụ không có liên hệ được liên kết), skipped_no_campaign (không có tác nhân hoặc chiến dịch nào có thể trả lời cho liên hệ đó) hoặc skipped_error. FAQ được tạo trong mọi trường hợp.

Xem FAQs API để quản lý FAQ kết quả.

Xóa một tác vụ

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

Các bước tiếp theo

API Danh bạ — liên kết các tác vụ với đúng người liên hệ
API Webhooks — nhận thông báo về Task Created, Task Updated và Task Completed
Tham chiếu API — trình khám phá điểm cuối tương tác đầy đủ

API Tác vụ #

Đối tượng tác vụ #

Tạo tác vụ #

Liệt kê tác vụ #

Tìm kiếm tác vụ #

Lấy một tác vụ #

Cập nhật một tác vụ #

Hoàn thành một tác vụ #

Di chuyển & sắp xếp lại (kanban) #

Các tác vụ cho một liên hệ #

Cấu hình bảng tác vụ #

Liệt kê các giai đoạn tác vụ #

Cập nhật các giai đoạn tác vụ #

Liệt kê các loại tác vụ #

Phê duyệt một đề xuất FAQ #

Xóa một tác vụ #

Các bước tiếp theo #

API Tác vụ

Đối tượng tác vụ

Tạo tác vụ

Liệt kê tác vụ

Tìm kiếm tác vụ

Lấy một tác vụ

Cập nhật một tác vụ

Hoàn thành một tác vụ

Di chuyển & sắp xếp lại (kanban)

Các tác vụ cho một liên hệ

Cấu hình bảng tác vụ

Liệt kê các giai đoạn tác vụ

Cập nhật các giai đoạn tác vụ

Liệt kê các loại tác vụ

Phê duyệt một đề xuất FAQ

Xóa một tác vụ

Các bước tiếp theo