# API Tugas

Tugas adalah hal-hal yang harus dilakukan dan tindak lanjut yang dilampirkan ke akun Anda — secara opsional ditautkan ke kontak, kesepakatan, atau kampanye. Tugas bergerak melalui **tahapan** papan tugas Anda (kolom kanban Anda) dan memiliki **tipe** serta **prioritas**. Panduan ini membahas cara mengelolanya melalui API.

- **URL Dasar** — `https://api.youraiconnector.com/v1`
- **Autentikasi** — kunci API Anda (lihat [Autentikasi](authentication.md))
- **Kesalahan & penomoran halaman** — lihat [Kesalahan & Penomoran Halaman](errors-and-pagination.md)

Semua contoh di bawah ini menunjukkan formulir kueri `?apiKey=` dalam cURL dan header `X-API-Key` dalam JavaScript dan Python — keduanya berfungsi di setiap endpoint.

---

## Objek tugas

```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`, atau tipe tugas yang Anda konfigurasi (lihat [Daftar tipe tugas](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high`, atau `urgent`.
- **`stage`** — id tahapan pada papan tugas Anda (lihat [Daftar tahapan tugas](#list-task-stages)). Jika tidak disertakan saat pembuatan, tugas akan masuk ke tahapan pertama Anda.
- **`remind_before_minutes`** — berapa menit sebelum `due_date` pengingat dikirimkan. `0` berarti tepat pada waktu jatuh tempo; hilangkan atau kirim `null` jika tidak ingin pengingat. Harus berupa bilangan bulat dari `0` hingga `1440` (1 hari) — nilai yang lebih besar akan ditolak. Pengingat memerlukan `due_date` untuk aktif, dan menjadwalkan ulang tugas akan memindahkan pengingat bersamanya.

---

## Membuat tugas

`POST /tasks` — hanya `title` yang wajib diisi.

::: note
**Catatan:** `due_date` menerima stempel waktu ISO 8601, termasuk waktu dalam sehari. Pasangkan dengan `remind_before_minutes` agar pengingat dikirimkan sesuai pengaturan notifikasi **Tugas** Anda. `contact_id`, `deal_id`, dan `campaign_id` menautkan tugas ke catatan tersebut. `assigned_to` adalah id pengguna anggota tim.
:::


> **Memastikan `assigned_to` benar.** Ini harus berupa id pengguna dari pemilik akun atau anggota tim aktif di akun yang sama. Titik akhir ini saat ini tidak memeriksanya, jadi id yang tidak dimiliki siapa pun akan diterima dan disimpan persis seperti yang Anda kirimkan — Anda tetap mendapatkan `201`. Salin id tersebut alih-alih mengetiknya ulang: id ini mencampur `l` dengan `L` dan huruf `O` dengan angka `0`, dan satu karakter yang salah sudah cukup untuk menyebabkan masalah. Untuk memeriksa apa yang sebenarnya Anda kirim, buka tugas di dasbor: kolom **Assignee** pada catatan tugas akan kembali menampilkan id mentah jika tidak cocok dengan siapa pun, dan pemilih penerima tugas di **Edit task** akan menampilkan **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"])
```

**Respons** (`201`)

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

---

## Mencantumkan tugas

`GET /tasks` — mengembalikan tugas untuk akun Anda, dengan filter opsional.

**Parameter kueri** (semuanya opsional): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (stempel waktu 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"]
```

**Respons** (`200`)

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

---

## Cari tugas

`POST /tasks/search` — pencocokan teks lengkap pada judul dan deskripsi, dengan filter opsional yang sama seperti pencantuman.

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

---

## Dapatkan tugas

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

Tugas yang tidak ada di akun Anda akan mengembalikan `404`.

---

## Perbarui tugas

`PUT /tasks/{taskId}` — kirim hanya kolom yang ingin Anda ubah (`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."},
)
```

---

## Selesaikan tugas

`POST /tasks/{taskId}/complete` — memindahkan tugas ke tahap selesai di papan Anda. Kolom opsional `notes` mencatat catatan penutup.

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

---

## Pindahkan & susun ulang (kanban)

**Pindahkan tugas ke tahap lain** — `POST /tasks/{taskId}/move` dengan `new_stage_id` (tahap tujuan) dan `new_position` (slot berbasis nol di dalam tahap tersebut; wajib, harus berupa bilangan bulat non-negatif):

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

**Susun ulang tugas dalam satu tahap** — `POST /tasks/reorder` dengan `stage_id` dan id tugas dalam urutan barunya:

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

---

## Tugas untuk kontak

`GET /tasks/contact/{contactId}` — setiap tugas ditautkan ke satu kontak.

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

---

## Konfigurasi papan tugas

### Daftar tahap tugas

`GET /tasks/stages` — kolom papan Anda, sesuai urutan. Gunakan `id` tahap sebagai kolom `stage` saat membuat atau memindahkan tugas.

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

### Perbarui tahap tugas

`PUT /tasks/stages` — ganti konfigurasi tahap papan Anda. Kirim array `stages` lengkap yang sudah diurutkan.

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

### Daftar jenis tugas

`GET /tasks/types` — jenis tugas yang dikonfigurasi di akun Anda (digunakan sebagai kolom `type`).

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

---

## Menyetujui saran FAQ

Saat bot AI mengusulkan FAQ baru, bot tersebut membuat tugas dengan tipe `faq_update`. `POST /tasks/{taskId}/approve-faq` mengubah saran tersebut menjadi FAQ nyata di basis pengetahuan agen AI yang mengajukannya dan menyelesaikan tugas tersebut. Anda dapat mengganti pertanyaan/jawaban di dalam badan pesan.

Tambahkan `"send_follow_up": true` agar AI juga segera mengirimkan jawaban kepada kontak yang ditautkan ke tugas tersebut, sebagai pesan alami dalam obrolan itu (hal yang sama yang dilakukan tombol **Kirim jawaban ke kontak sekarang** di aplikasi). Balasan dikirim melalui agen AI yang menangani kontak tersebut.

```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` memberi tahu Anda apa yang terjadi pada pesan tersebut: `not_requested` (bendera tidak disetel), `published` (terkirim), `queued` (bot sedang membalas kontak tersebut, jawaban akan dikirim segera setelah selesai), `skipped_no_contact` (tugas tidak memiliki kontak yang ditautkan), `skipped_no_campaign` (tidak ada agen atau kampanye yang dapat menjawab untuk kontak tersebut) atau `skipped_error`. FAQ tetap dibuat dalam setiap kasus.

Lihat [API FAQ](faqs.md) untuk mengelola FAQ yang dihasilkan.

---

## Menghapus tugas

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

---

## Langkah berikutnya

- [API Kontak](contacts.md) — tautkan tugas ke kontak yang tepat
- [API Webhook](webhooks.md) — dapatkan pemberitahuan tentang `Task Created`, `Task Updated`, dan `Task Completed`
- [Referensi API](reference.md) — penjelajah endpoint interaktif lengkap