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 KelkiGET /agent/conversations/{conversation_id}— Lire l'état d'une conversationPOST /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 |
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 |
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 |
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 |
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 |
Conversation
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string | oui | |
object | string | oui | valeur : |
mode | string | oui | valeurs : |
step | string | oui | valeurs : |
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 |
fallback | string | null | non |
valeurs : |
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 : |
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 : |
consent_text_version | string | non | motif |
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 |
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. |