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 :
| Champ | Usage | Modèle d'IA |
|---|---|---|
text | texte libre de la personne (600 caractères au plus) | oui |
choice | valeur d'un bouton de choices | non |
data | champs structurés : trade_id, service, other_need, delay, place_id, contact, message | non |
consent | true, avec consent_text_version, à l'étape recap seulement | non |
É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
- Réponses masquées : tout e-mail ou numéro dans le texte de l'agent apparaît masqué (
c•••@example.com,+33 6 •• •• •• 42). - Les choix et les données structurées sont toujours recalculés depuis la demande validée : un message ne peut pas forcer une valeur hors liste.
- Le texte libre n'est pas conservé ; les messages à l'agent sont plafonnés par jour selon votre plan (limites).
- Une conversation d'un autre compte renvoie
404.