POST/api/v2/ai/agents/{id}/replies
Ask the AI for an answer
An AI Agent's answer to one customer message in your app, with that agent's Behaviour, knowledge, and Q&A.
Klik Flow sends nothing to the customer: your app shows reply. Send only the new message; Klik Flow remembers the last 16 turns of the session for 24 hours after its last message, and answers one message at a time per session. An answer takes a few seconds, so give the request a 60-second timeout. Live keys use AI credits at the price "AI Agent answers for apps (API)" (Jawaban AI Agent untuk aplikasi (API)); test keys answer within the free AI test quota (Uji AI) and use no credits. Call it from your app's server only, with an Idempotency-Key. See the Ask an AI Agent guide.
Send an Idempotency-Key header (for example a new UUID per request). A repeat with the same key within 24 hours gets the first answer again, so nothing is sent twice.
After outcome: "handoff", show reply, then direct the customer to your team: the next message in that session gets session_handoff (409) until the session is closed or 24 hours pass.
Path parameters
idintegerrequiredAgent id from List AI Agents.
Body (JSON)
messagestringrequiredThe customer's message, at most 4,000 characters.
session_idstringrequiredA session id from your app, one per app user: 1–128 letters, digits, or
. _ : @ -. Messages with the samesession_idare answered with their history in mind.customerobjectOptional:
{ "ref", "name", "phone" }.nameis used to greet the customer.phone(8–15 digits with the country code) opens that customer's order status when the key also has thecontacts:readscope and the agent's order status switch in AI Agent › Integration (AI Agent › Integrasi) is on.ref(the customer's id in your app) is accepted but not used to answer.formatstring: plain | whatsapp | markdownShape of the
replytext:plainwithout formatting (default),whatsappwith *bold* and _italics_, ormarkdown.
Possible errors
- 400
invalid_jsonBody is not valid JSON - 400
idempotency_key_invalidInvalid Idempotency-Key - 401
missing_keyAPI key not sent - 401
key_invalidUnknown API key - 401
key_revokedAPI key revoked - 401
key_expiredAPI key expired - 401
member_inactiveKey creator is no longer a member - 402
ai_credit_emptyAI credits used up - 403
ip_not_allowedServer IP not in the key's list - 403
plan_no_apiPlan does not include the API for live keys - 403
tenant_blockedBusiness access suspended - 403
scope_missingKey lacks this permission - 403
permission_missingKey creator's role lacks this permission - 403
agent_not_api_enabledAI Agent not opened to the API - 403
ai_feature_offAI for apps is turned off - 404
agent_not_foundAI Agent not found - 409
idempotency_conflictIdempotency-Key used for different content - 409
request_in_progressThe same request is still being processed - 409
session_handoffSession handed over to a person - 409
session_busyThe previous answer in this session is not finished - 422
invalid_requestInvalid field - 422
invalid_phoneInvalid destination number - 422
message_too_longMessage too long - 429
rate_limitedToo many requests per minute - 429
session_limitAI answer limit reached - 500
internal_errorProblem at Klik Flow - 503
ai_unavailableThe AI could not answer
Try it
Try it with a test key
/api/v2/ai/agents/{id}/replies