# 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](https://kelki.ai/developers/fr/consent/)). 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](https://kelki.ai/developers/fr/guides/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](https://kelki.ai/developers/fr/rate-limits/)). - Une conversation d'un autre compte renvoie `404`. ## Sur cette page - URL : https://kelki.ai/developers/fr/guides/agent/ - Langue : fr - fr : https://kelki.ai/developers/fr/guides/agent/ - en : https://kelki.ai/developers/en/guides/agent/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt