Guide: embed the Kelki Agent
The same agent as the kelki.ai chat bubble. You pass it the person's messages; it finds the trade, the service, the timing and the place, collects the contact details, then presents a summary and the consent text.
Start a conversation
curl -s https://kelki.ai/api/v1/agent/conversations \
-H "Authorization: Bearer $KELKI_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: conv-resa-0042-1" \
-d '{"country":"FR","lang":"fr","first_message":"Volet roulant bloqué en bas","reference":"resa-2026-0042"}'
Response: a Conversation with step, text (the agent's message), choices (buttons to display), and later recap, consent, request_id, fallback. Scope agent; the conversation is forgotten 2 hours after the last message.
Send a message
POST /agent/conversations/{conversation_id}/messages, with only one of these fields:
| Field | Use | AI model |
|---|---|---|
text | the person's free text (600 characters at most) | yes |
choice | value of a button from choices | no |
data | structured fields: trade_id, service, other_need, delay, place_id, contact, message | no |
consent | true, with consent_text_version, at the recap step only | no |
Possible steps: metier, metier_choix, besoin, besoin_libre, delai, lieu, lieu_choix, coordonnees, recap, envoyee (stable identifiers, in French). If your app already knows the place or the contact details, send them as data: fewer questions, no model call.
Summary and consent
At the recap step, display recap then consent.text word for word, unticked box (rules). When the person ticks it:
{"consent": true, "consent_text_version": "v2026-10-18"}
The agent then creates the draft and starts the e-mail confirmation, exactly like POST /requests then POST /requests/{request_id}/confirmation: the requests.write scope is also required. request_id gives the request, to track like any other.
Falling back to the form
If the agent cannot go on (daily budget reached, model unavailable), the response carries "fallback": "form": continue with your screens and POST /requests (form guide). If the agent is paused, 503 agent_paused.
What the agent guarantees
- Masked responses: any e-mail or number in the agent's text appears masked (
c•••@example.com,+33 6 •• •• •• 42). - Choices and structured data are always recomputed from the validated request: a message cannot force a value outside the lists.
- Free text is not stored; messages to the agent are capped per day according to your plan (limits).
- A conversation of another account returns
404.