Docs menuAsk an AI Agent
API documentationBahasa Indonesia

Ask an AI Agent from your app.

Your own app can ask a Klik Flow AI Agent to answer customer messages. The agent answers with the same Behaviour, knowledge, and Q&A as in WhatsApp chats. Klik Flow sends nothing to the customer: your app shows the answer.

Do AI Agent answers through the API use AI credits?

Yes, with a live key: every answer uses AI credits at the price "AI Agent answers for apps (API)" (Jawaban AI Agent untuk aplikasi (API)), and the amount is in `credits_used`. Test keys answer within the free AI test quota (Uji AI) and never use credits.

When to use it

Use it when customers ask questions in your own mobile app, website, or ticket system and you want a Klik Flow AI Agent to answer. WhatsApp chats that come into Klik Flow are already answered by the AI Agent directly, without this API.

  • Turn on "Usable through the API" (Bisa dipakai lewat API) in AI Agent › Integration (AI Agent › Integrasi) for every agent that may be asked.
  • Create a key in Settings › API & Webhook (Pengaturan › API & Webhook) with the ai:reply scope (AI Agent: minta jawaban). A key can be limited to specific agents and given its own answers-per-day limit.
  • Get the agent's id from GET /api/v2/ai/agents.
  • The "Answer for apps" feature (Jawab untuk aplikasi) in Settings › AI & credits (Pengaturan › AI & kredit) must be on; when it is off, requests are refused with ai_feature_off.

Keep the key on your server

The API key is a secret. Your mobile app or web page sends the customer's message to your server, then your server calls Klik Flow and passes the answer back. Never put the key in a mobile app or web page code.

Ask for an answer

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

Successful response:

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

An answer takes a few seconds, so give the request a 60-second timeout. format sets the shape of the reply text: plain (default), whatsapp, or markdown.

session_id and history

Send the same session_id for one app user, and send only the new message. Klik Flow remembers the last 16 turns of that session for 24 hours after its last message, so the agent understands follow-up questions such as "and the blue one?".

  • One answer at a time per session. A second message that arrives while the first answer is not finished waits briefly, then is refused with session_busy (409) and Retry-After: 2.
  • GET /api/v2/ai/sessions/{session_id} shows the remembered history, its status, and expires_at.
  • DELETE /api/v2/ai/sessions/{session_id} closes the session: the history is gone and the per-session answer count starts from zero.
  • After 24 hours without a message, the session starts fresh.

Outcomes and handoffs

outcome describes the answer:

  • answered: answered from knowledge, Q&A, or store data.
  • partial: only part could be answered; reply holds that part.
  • unanswerable: no source answers it; reply holds the agent's fallback text set in Behaviour (Perilaku).
  • handoff: the agent hands the customer over to a person, with the reason in handoff_reason (for example customer_requested_human). Show reply, then direct the customer to your team. The next message in that session is refused with session_handoff (409) until the session is closed or 24 hours pass.
  • skipped: reply is null. skip_reason holds outside_hours (outside the agent's active hours) or no_question (nothing to answer).

Credits and limits

  • Live keys: every answer uses AI credits at the price "AI Agent answers for apps (API)"; the amount is in credits_used. When the balance is empty, requests are refused with ai_credit_empty (402): show your own fallback message.
  • Test keys: answer within the free AI test quota (Uji AI) and never use credits (credits_used: 0, test: true).
  • Per session: set in AI Agent › Behaviour › Reply limit per chat (AI Agent › Perilaku › Batas balasan per chat).
  • Per business per day: set by the plan (default 2,000), reset at midnight in the business's time zone. A key can be given its own lower limit; GET /api/v2/me shows it in ai_daily_limit, and the agents it may ask in ai_agents.
  • A reached limit is refused with session_limit (429); for the daily limit, wait for Retry-After.
  • After session_busy, session_handoff (once the session is closed), or ai_credit_empty (once credits are topped up), send the message again with the same Idempotency-Key: these refusals are not stored, and the earlier message was not answered, so nothing is counted twice.
  • ai_unavailable (503): no credits were used; retry with the same Idempotency-Key.

Files, order status, and history

  • media holds files the agent picked, for example product photos, as temporary links valid for 24 hours (expires_at). Download or show them before they expire.
  • Order status is read only when you send customer.phone, the key also has the contacts:read scope, and the switch "Open order status when the app sends the customer's number" (Buka status pesanan bila aplikasi mengirim nomor pelanggan) in AI Agent › Integration is on.
  • When "Keep Q&A text for 30 days" (Simpan isi tanya-jawab 30 hari) is on, questions and answers appear for 30 days in the API history (Riwayat API) in AI Agent › Integration, and questions that could not be answered go to AI suggestions (Saran AI).

Send WhatsApp from your system with the Klik Flow API.

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