Menu dokumentasiTanya AI Agent
Dokumentasi APIEnglish

Tanya AI Agent dari aplikasi Anda.

Aplikasi Anda sendiri bisa meminta jawaban AI Agent Klik Flow untuk pesan pelanggan. Agent menjawab dengan Perilaku, pengetahuan, dan Tanya-jawab yang sama seperti di chat WhatsApp. Klik Flow tidak mengirim apa pun ke pelanggan: aplikasi Anda yang menampilkan jawabannya.

Apakah jawaban AI Agent lewat API memotong kredit AI?

Ya, untuk kunci live: setiap jawaban memotong kredit AI dengan tarif "Jawaban AI Agent untuk aplikasi (API)", dan jumlahnya ada di `credits_used`. Kunci tes menjawab dalam kuota Uji AI gratis dan tidak pernah memotong kredit.

Kapan dipakai

Pakai bila pelanggan bertanya di aplikasi HP, website, atau sistem tiket Anda sendiri, dan Anda ingin AI Agent Klik Flow yang menjawab. Chat WhatsApp yang masuk ke Klik Flow sudah dijawab AI Agent langsung, tanpa API ini.

  • Nyalakan "Bisa dipakai lewat API" di AI Agent › Integrasi untuk setiap agent yang boleh ditanya.
  • Buat kunci di Pengaturan › API & Webhook dengan izin ai:reply (AI Agent: minta jawaban). Kunci bisa dibatasi ke agent tertentu dan diberi batas jawaban per hari sendiri.
  • Ambil id agent dari GET /api/v2/ai/agents.
  • Fitur "Jawab untuk aplikasi" di Pengaturan › AI & kredit harus menyala; bila mati, permintaan ditolak ai_feature_off.

Kunci hanya di server

Kunci API adalah rahasia. Aplikasi HP atau halaman web Anda mengirim pesan pelanggan ke server Anda, lalu server Anda yang memanggil Klik Flow dan meneruskan jawabannya. Jangan menaruh kunci di aplikasi HP atau kode halaman web.

Minta jawaban

curl -X POST "https://klikflow.id/api/v2/ai/agents/4/replies" \
  -H "Authorization: Bearer KUNCI_API" \
  -H "Idempotency-Key: 3c9e1f2a-7b4d-4e8a-9f1c-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{"message":"Kak, kemeja batik ukuran L masih ada?","session_id":"app-user-8812","customer":{"name":"Rina"}}'

Jawaban berhasil:

{
  "data": {
    "object": "ai_reply",
    "agent_id": 4,
    "session_id": "app-user-8812",
    "reply": "Masih ada, Kak Rina. Kemeja batik ukuran L tersedia untuk motif Parang dan Kawung, harganya Rp185.000. Mau saya kirim fotonya?",
    "outcome": "answered",
    "handoff": false,
    "handoff_reason": null,
    "skip_reason": null,
    "sources": [{ "type": "catalog", "title": "Kemeja Batik Parang" }],
    "media": [],
    "credits_used": 1.4,
    "test": false
  }
}

Jawaban butuh beberapa detik, jadi beri batas waktu permintaan 60 detik. format mengatur bentuk teks reply: plain (bawaan), whatsapp, atau markdown.

session_id dan riwayat

Kirim session_id yang sama untuk satu pengguna aplikasi, dan kirim hanya pesan barunya. Klik Flow mengingat 16 giliran terakhir sesi itu selama 24 jam sejak pesan terakhir, jadi agent memahami pertanyaan lanjutan seperti "kalau yang biru ada?".

  • Satu jawaban sekaligus per sesi. Pesan kedua yang datang saat jawaban pertama belum selesai menunggu sebentar, lalu ditolak session_busy (409) dengan Retry-After: 2.
  • GET /api/v2/ai/sessions/{session_id} menampilkan riwayat yang diingat, statusnya, dan expires_at.
  • DELETE /api/v2/ai/sessions/{session_id} menutup sesi: riwayat hilang dan hitungan jawaban per sesi mulai dari nol.
  • Setelah 24 jam tanpa pesan, sesi mulai lagi dari awal.

Hasil jawaban dan oper ke admin

outcome menjelaskan jawaban itu:

  • answered: dijawab dari pengetahuan, Tanya-jawab, atau data toko.
  • partial: hanya sebagian yang bisa dijawab; reply memuat bagian itu.
  • unanswerable: tidak ada sumber yang menjawab; reply berisi teks cadangan agent sesuai Perilaku.
  • handoff: agent mengoper pelanggan ke admin, dengan alasan di handoff_reason (misalnya customer_requested_human). Tampilkan reply, lalu arahkan pelanggan ke tim Anda. Pesan berikutnya di sesi itu ditolak session_handoff (409) sampai sesi ditutup atau 24 jam berlalu.
  • skipped: reply berisi null. skip_reason berisi outside_hours (di luar jam aktif agent) atau no_question (tidak ada yang perlu dijawab).

Kredit dan batas

  • Kunci live: setiap jawaban memotong kredit AI dengan tarif "Jawaban AI Agent untuk aplikasi (API)"; jumlahnya ada di credits_used. Bila saldo habis, permintaan ditolak ai_credit_empty (402): tampilkan pesan cadangan Anda sendiri.
  • Kunci tes: menjawab dalam kuota Uji AI gratis dan tidak pernah memotong kredit (credits_used: 0, test: true).
  • Per sesi: sesuai AI Agent › Perilaku › Batas balasan per chat.
  • Per bisnis per hari: sesuai paket (bawaan 2.000), dihitung ulang tengah malam waktu bisnis. Kunci bisa diberi batas sendiri yang lebih rendah; GET /api/v2/me menampilkannya di ai_daily_limit, dan agent yang boleh ditanya di ai_agents.
  • Batas yang tercapai ditolak session_limit (429); untuk batas harian, tunggu sesuai Retry-After.
  • Setelah session_busy, session_handoff (lalu sesi ditutup), atau ai_credit_empty (lalu kredit diisi), kirim pesan itu lagi dengan Idempotency-Key yang sama: penolakan ini tidak disimpan, dan pesan tadi belum dijawab, jadi tidak ada yang terhitung dua kali.
  • ai_unavailable (503): kredit tidak terpotong; kirim ulang dengan Idempotency-Key yang sama.

File, status pesanan, dan riwayat

  • media berisi file yang dipilih agent, misalnya foto produk, sebagai link sementara yang berlaku 24 jam (expires_at). Unduh atau tampilkan sebelum waktunya habis.
  • Status pesanan hanya dibaca bila Anda mengirim customer.phone, kunci juga punya izin contacts:read, dan saklar "Buka status pesanan bila aplikasi mengirim nomor pelanggan" di AI Agent › Integrasi menyala.
  • Bila "Simpan isi tanya-jawab 30 hari" menyala, pertanyaan dan jawaban tampil 30 hari di Riwayat API (AI Agent › Integrasi), dan pertanyaan yang belum bisa dijawab masuk Saran AI.

Kirim WhatsApp dari sistem Anda lewat API Klik Flow.

Mulai dengan paket Free. Ajak tim setelah ruang kerja siap.