Aller au contenu
KelkiDéveloppeurs

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

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

NomOùRequisTypeDescription
Idempotency-Keyheaderouistring

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

CodeDescriptionContenu
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

NomOùRequisTypeDescription
conversation_idpathouistring

motif ^conv_[0-9A-Za-z]{20,40}$

Réponses

CodeDescriptionContenu
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

NomOùRequisTypeDescription
conversation_idpathouistring

motif ^conv_[0-9A-Za-z]{20,40}$

Idempotency-Keyheaderouistring

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

CodeDescriptionContenu
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

ChampTypeRequisDescription
countryCountryCodenon
langLanguageCodenon
first_messagestringnon

max. 600 car.

referencePartnerReferencenon
end_user_refstringnon

motif ^[A-Za-z0-9_\-]{6,64}$

Conversation

ChampTypeRequisDescription
idstringoui
objectstringoui

valeur : conversation

modestringoui

valeurs : test, live

stepstringoui

valeurs : metier, metier_choix, besoin, besoin_libre, delai, lieu, lieu_choix, coordonnees, recap, envoyee

textstringoui

Texte de l'agent ; tout e-mail ou numéro y est masqué.

choicestableau de Choiceoui
recapstring | nullnon

Récapitulatif masqué (étape recap).

consentConsentText ou nullnon
request_idstring | nullnon

Demande créée après consent: true.

fallbackstring | nullnon

form : l'agent passe la main (budget, panne du modèle) ; continuez avec POST /requests.

valeurs : form,

expires_atstring (date-time)oui

Problem

Détails d'un problème (RFC 9457), avec des membres d'extension.

ChampTypeRequisDescription
typestring (uri)oui

URI stable du type de problème ; elle mène à sa documentation.

titlestringoui
statusintegeroui

min. 400 · max. 599

detailstringnon
instancestring (uri-reference)non
codestringoui

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_idstringoui
errorstableau de FieldErrornon

AgentMessage

ChampTypeRequisDescription
textstringnon

max. 600 car.

choicestringnon

max. 200 car.

dataobjectnon
consentbooleannon

valeur : True

consent_text_versionstringnon

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

ChampTypeRequisDescription
valuestringoui
labelstringoui
hintstringnon

ConsentText

ChampTypeRequisDescription
versionstringoui

motif ^v\d{4}-\d{2}-\d{2}$

langLanguageCodeoui
textstringoui

À afficher mot pour mot, à côté d'une case non cochée par défaut.

valid_fromstring (date)oui

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

Valeurs acceptées, quand la liste est fermée.