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)
Kesalahan & penomoran halaman — lihat Kesalahan & Penomoran Halaman

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

{
  "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).
priority — none, low, normal, high, atau urgent.
stage — id tahapan pada papan tugas Anda (lihat Daftar tahapan tugas). 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.

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

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

Respons (201)

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

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

Respons (200)

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

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

Dapatkan tugas

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

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

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

Selesaikan tugas

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

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

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

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:

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

Tugas untuk kontak

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

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

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.

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

Perbarui tahap tugas

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

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

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.

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 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 untuk mengelola FAQ yang dihasilkan.

Menghapus tugas

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

Langkah berikutnya

API Kontak — tautkan tugas ke kontak yang tepat
API Webhook — dapatkan pemberitahuan tentang Task Created, Task Updated, dan Task Completed
Referensi API — penjelajah endpoint interaktif lengkap

API Tugas #

Objek tugas #

Membuat tugas #

Mencantumkan tugas #

Cari tugas #

Dapatkan tugas #

Perbarui tugas #

Selesaikan tugas #

Pindahkan & susun ulang (kanban) #

Tugas untuk kontak #

Konfigurasi papan tugas #

Daftar tahap tugas #

Perbarui tahap tugas #

Daftar jenis tugas #

Menyetujui saran FAQ #

Menghapus tugas #

Langkah berikutnya #

API Tugas

Objek tugas

Membuat tugas

Mencantumkan tugas

Cari tugas

Dapatkan tugas

Perbarui tugas

Selesaikan tugas

Pindahkan & susun ulang (kanban)

Tugas untuk kontak

Konfigurasi papan tugas

Daftar tahap tugas

Perbarui tahap tugas

Daftar jenis tugas

Menyetujui saran FAQ

Menghapus tugas

Langkah berikutnya