Aller au contenu
KelkiDéveloppeurs

Guide : intégrer l'Agent Kelki

Le même agent que la bulle de kelki.ai. Vous lui passez les messages de la personne ; il trouve le métier, la prestation, le délai, le lieu, recueille les coordonnées, puis présente un récapitulatif et le texte d'accord.

Démarrer une 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"}'

Réponse : une Conversation avec step (étape), text (message de l'agent), choices (boutons à afficher), et plus tard recap, consent, request_id, fallback. Portée agent ; la conversation est oubliée 2 heures après le dernier message.

Envoyer un message

POST /agent/conversations/{conversation_id}/messages, avec un seul de ces champs :

ChampUsageModèle d'IA
texttexte libre de la personne (600 caractères au plus)oui
choicevaleur d'un bouton de choicesnon
datachamps structurés : trade_id, service, other_need, delay, place_id, contact, messagenon
consenttrue, avec consent_text_version, à l'étape recap seulementnon

Étapes possibles : metier, metier_choix, besoin, besoin_libre, delai, lieu, lieu_choix, coordonnees, recap, envoyee. Si votre application connaît déjà le lieu ou les coordonnées, envoyez-les en data : moins de questions, aucun appel au modèle.

Le récapitulatif et l'accord

À l'étape recap, affichez recap puis consent.text mot pour mot, case non cochée (règles). Quand la personne coche :

{"consent": true, "consent_text_version": "v2026-10-18"}

L'agent crée alors le brouillon et lance la confirmation par e-mail, exactement comme POST /requests puis POST /requests/{request_id}/confirmation : la portée requests.write est exigée en plus. request_id donne la demande, à suivre comme les autres.

La bascule vers le formulaire

Si l'agent ne peut pas continuer (budget quotidien atteint, modèle indisponible), la réponse porte "fallback": "form" : poursuivez avec vos écrans et POST /requests (guide du formulaire). Si l'agent est en pause, 503 agent_paused.

Ce que l'agent garantit