# 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](https://kelki.ai/developers/en/consent/)). 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](https://kelki.ai/developers/en/guides/form/)). 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](https://kelki.ai/developers/en/rate-limits/)). - A conversation of another account returns `404`. ## About this page - URL : https://kelki.ai/developers/en/guides/agent/ - Language : en - fr : https://kelki.ai/developers/fr/guides/agent/ - en : https://kelki.ai/developers/en/guides/agent/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt