Agent API

Agent API adalah akses read-only untuk AI agent, automation, atau connector yang perlu membaca data workspace Dalekta secara aman. API key dibuat dari menu API & Webhook dan selalu terikat ke workspace aktif saat key dibuat.

Untuk integrasi agent, cukup siapkan URL instruksi dan Agent API base URL. URL SKILL.md dipakai AI agent untuk membaca daftar endpoint dan aturan API secara machine-readable.

1. Buka dashboard Dalekta.
2. Pilih workspace yang benar dari switcher workspace.
3. Masuk ke menu API & Webhook.
4. Klik tombol Tambah API key.
5. Isi nama key, misalnya OpenClaw Agent, Claude Connector, atau Automasi Operasional.
6. Pilih scope sesuai kebutuhan agent.
7. Jika memilih agent.chats.read, pilih WhatsApp session yang boleh dibaca.
8. Klik Buat key.
9. Copy plaintext API key saat modal sukses muncul. Key hanya ditampilkan satu kali.

Semua endpoint Agent API selain SKILL.md membutuhkan Bearer token. Simpan API key di secret manager atau environment server-side, bukan di frontend publik.

curl "https://dalekta.id/api/agent/workspace" \
  -H "Authorization: Bearer dlk_live_xxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Scope agent.chats.read saja belum cukup untuk membaca chat customer. API key juga harus punya WhatsApp session allowlist. Ini mencegah agent membaca chat dari nomor sales/CS lain yang tidak dipilih.

• Allowlist dipilih saat membuat API key jika agent.chats.read aktif.
• Allowlist bisa diedit dari tabel API key dengan tombol Akses.
• Jika lead memakai WhatsApp session di luar allowlist, endpoint messages mengembalikan 403.
• Jika key tidak punya scope chat, endpoint messages juga mengembalikan 403.

Contoh ini menunjukkan cara agent menerjemahkan pertanyaan user menjadi request API. Untuk kata seperti hari ini, minggu ini, atau bulan ini, agent sebaiknya membaca timezone workspace dulu dari /api/agent/workspace, lalu mengubahnya menjadi range from/to atau createdFrom/createdTo.

User: tolong cek berapa leads hari ini
Agent steps:
1. GET /api/agent/workspace untuk membaca timezone workspace.
2. Hitung range hari ini sesuai timezone workspace.
3. GET /api/agent/analytics/summary?from=<awal_hari>&to=<akhir_hari>.
4. Jawab ringkas: total Masuk WA, MQL, Prospek, Closing, revenue, dan catatan jika ada angka yang perlu dicek.

Contoh jawaban:
Hari ini ada 18 lead Masuk WA, 7 MQL, 3 Prospek, dan 2 Closing. Revenue tercatat Rp2.500.000. Dari sisi funnel, rasio Closing ke Masuk WA sekitar 11,11%.

Error Agent API memakai format JSON konsisten supaya agent bisa mengambil keputusan tanpa parsing teks bebas.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: agent.chats.read",
    "requestId": "req_..."
  }
}

• Buat satu API key per agent atau integration agar revoke dan audit lebih jelas.
• Pakai scope terkecil yang masih cukup untuk pekerjaan agent.
• Untuk agent yang membaca chat, pilih hanya WhatsApp session yang relevan.
• Simpan API key di secret manager atau environment server-side, bukan di frontend publik, screenshot, atau chat grup.
• Gunakan pagination dan filter tanggal supaya agent tidak menarik data terlalu besar.
• Revoke key yang tidak dipakai lagi dari menu API & Webhook.