# Agent Conversation avec l'Agent Kelki (même cerveau que la bulle du site et l'A2A). Adresse de base : `https://kelki.ai/api/v1`. - POST /agent/conversations — Démarrer une conversation avec l'Agent Kelki - GET /agent/conversations/{conversation_id} — Lire l'état d'une conversation - POST /agent/conversations/{conversation_id}/messages — Envoyer un message à l'Agent Kelki ## POST `/agent/conversations` Démarrer une conversation avec l'Agent Kelki Conversation rattachée au compte et au mode. Oubliée 2 heures après le dernier message. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `agent`). ### Paramètres | Nom | Où | Requis | Type | Description | | `Idempotency-Key` | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif `^[A-Za-z0-9_\-]{8,64}$` | ### Corps de la requête `application/json` — ConversationCreate ``` { "country": "FR", "lang": "fr", "first_message": "Le volet roulant du salon est bloqué en position basse.", "reference": "resa-2026-0042" } ``` ### Réponses | Code | Description | Contenu | | `201` | Conversation créée, avec la première réponse de l'agent. | `application/json` Conversation | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `403` | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | | `503` | Service en pause ou en maintenance (ex. agent en pause, création live suspendue). | `application/problem+json` Problem | ### Exemple de réponse ``` { "id": "conv_01JC00000000000000000000CV", "object": "conversation", "mode": "test", "step": "metier_choix", "text": "Lequel de ces professionnels correspond à votre besoin ?", "choices": [ { "value": "metier:volets-roulants", "label": "Réparateur de volets roulants" }, { "value": "metier:serrurier", "label": "Serrurier" } ], "recap": null, "consent": null, "request_id": null, "fallback": null, "expires_at": "2026-11-11T11:43:00Z" } ``` ## GET `/agent/conversations/{conversation_id}` Lire l'état d'une conversation Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `agent`). ### Paramètres | Nom | Où | Requis | Type | Description | | `conversation_id` | path | oui | string | motif `^conv_[0-9A-Za-z]{20,40}$` | ### Réponses | Code | Description | Contenu | | `200` | État de la conversation. | `application/json` Conversation | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `404` | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | `application/problem+json` Problem | ## POST `/agent/conversations/{conversation_id}/messages` Envoyer un message à l'Agent Kelki Un message contient un seul de : `text` (texte libre, passe par le modèle), `choice` (valeur d'un bouton), `data` (champs structurés), `consent` (accord de la personne à l'étape `recap`). `consent: true` crée un brouillon puis lance la confirmation par e-mail, exactement comme `POST /requests` + `POST /requests/{id}/confirmation` (portée `requests.write` exigée en plus). Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `agent`) ou jeton OAuth 2.0 (portée `agent`, `requests.write`). ### Paramètres | Nom | Où | Requis | Type | Description | | `conversation_id` | path | oui | string | motif `^conv_[0-9A-Za-z]{20,40}$` | | `Idempotency-Key` | header | oui | string | 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. motif `^[A-Za-z0-9_\-]{8,64}$` | ### Corps de la requête `application/json` — AgentMessage (obligatoire) ``` { "choice": "metier:volets-roulants" } ``` ### Réponses | Code | Description | Contenu | | `200` | Réponse de l'agent. | `application/json` Conversation | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `403` | Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. | `application/problem+json` Problem | | `404` | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | `application/problem+json` Problem | | `422` | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | | `503` | Service en pause ou en maintenance (ex. agent en pause, création live suspendue). | `application/problem+json` Problem | ## Schémas ### `ConversationCreate` | Champ | Type | Requis | Description | | `country` | CountryCode | non | | | `lang` | LanguageCode | non | | | `first_message` | string | non | max. 600 car. | | `reference` | PartnerReference | non | | | `end_user_ref` | string | non | motif `^[A-Za-z0-9_\-]{6,64}$` | ### `Conversation` | Champ | Type | Requis | Description | | `id` | string | oui | | | `object` | string | oui | valeur : `conversation` | | `mode` | string | oui | valeurs : `test`, `live` | | `step` | string | oui | valeurs : `metier`, `metier_choix`, `besoin`, `besoin_libre`, `delai`, `lieu`, `lieu_choix`, `coordonnees`, `recap`, `envoyee` | | `text` | string | oui | Texte de l'agent ; tout e-mail ou numéro y est masqué. | | `choices` | tableau de Choice | oui | | | `recap` | string | null | non | Récapitulatif masqué (étape recap). | | `consent` | ConsentText ou null | non | | | `request_id` | string | null | non | Demande créée après `consent: true`. | | `fallback` | string | null | non | `form` : l'agent passe la main (budget, panne du modèle) ; continuez avec POST /requests. valeurs : `form`, `` | | `expires_at` | string (date-time) | oui | | ### `Problem` Détails d'un problème (RFC 9457), avec des membres d'extension. | Champ | Type | Requis | Description | | `type` | string (uri) | oui | URI stable du type de problème ; elle mène à sa documentation. | | `title` | string | oui | | | `status` | integer | oui | min. 400 · max. 599 | | `detail` | string | non | | | `instance` | string (uri-reference) | non | | | `code` | string | oui | Code stable, lisible par une machine. valeurs : `invalid_json`, `invalid_parameter`, `payload_too_large`, `unsupported_media_type`, `invalid_credentials`, `expired_token`, `insufficient_scope`, `live_not_enabled`, `account_suspended`, `country_not_available`, `trade_not_available`, `not_found`, `invalid_state`, `idempotency_in_progress`, `idempotency_key_reused`, `validation_failed`, `consent_missing`, `consent_version_outdated`, `contact_limit_reached`, `duplicate_request`, `rate_limited`, `quota_exceeded`, `agent_paused`, `live_creation_paused`, `service_unavailable`, `internal_error` | | `request_id` | string | oui | | | `errors` | tableau de FieldError | non | | ### `AgentMessage` | Champ | Type | Requis | Description | | `text` | string | non | max. 600 car. | | `choice` | string | non | max. 200 car. | | `data` | object | non | | | `consent` | boolean | non | valeur : `True` | | `consent_text_version` | string | non | motif `^v\d{4}-\d{2}-\d{2}$` | ### `CountryCode` Type : string — motif `^[A-Z]{2}$` · défaut `"FR"` ### `LanguageCode` Type : string — motif `^[a-z]{2}$` ### `PartnerReference` Votre référence (ex. n° de réservation). Sans donnée personnelle. Renvoyée dans les webhooks. Type : string — motif `^[A-Za-z0-9._:\-]{1,64}$` ### `Choice` | Champ | Type | Requis | Description | | `value` | string | oui | | | `label` | string | oui | | | `hint` | string | non | | ### `ConsentText` | Champ | Type | Requis | Description | | `version` | string | oui | motif `^v\d{4}-\d{2}-\d{2}$` | | `lang` | LanguageCode | oui | | | `text` | string | oui | À afficher mot pour mot, à côté d'une case non cochée par défaut. | | `valid_from` | string (date) | oui | | ### `FieldError` | Champ | Type | Requis | Description | | `pointer` | string | oui | JSON Pointer (RFC 6901) du champ en cause. | | `detail` | string | oui | | | `allowed` | tableau de string | non | Valeurs acceptées, quand la liste est fermée. | ## Sur cette page - URL : https://kelki.ai/developers/fr/reference/agent/ - Langue : fr - fr : https://kelki.ai/developers/fr/reference/agent/ - en : https://kelki.ai/developers/en/reference/agent/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt