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

Sumber: https://klikflow.id/docs/api/tanya-ai-agent

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