# 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](authentication.md))
- **Lỗi & phân trang** — xem [Lỗi & Phân trang](errors-and-pagination.md)

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ụ

```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`, 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ụ](#list-task-types)).
- **`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ụ](#list-task-stages)). 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`.

::: note
**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**

```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"])
```

**Phản hồi** (`201`)

```json
{ "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**

```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"]
```

**Phản hồi** (`200`)

```json
{ "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ê.

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

---

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

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

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`).

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

---

## 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ụ.

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

---

## 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):

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

**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:

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

---

## 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ệ.

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

---

## 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ụ.

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

### 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.

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

### 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`).

```bash
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ệ đó.

```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` 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](faqs.md) để quản lý FAQ kết quả.

---

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

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

---

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

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