Skip to content
KelkiDevelopers

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:

FieldUseAI model
textthe person's free text (600 characters at most)yes
choicevalue of a button from choicesno
datastructured fields: trade_id, service, other_need, delay, place_id, contact, messageno
consenttrue, with consent_text_version, at the recap step onlyno

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.

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