# Agent Conversation with the Kelki Agent (same brain as the website chat bubble and A2A). Base URL: `https://kelki.ai/api/v1`. - POST /agent/conversations — Start a conversation with the Kelki Agent - GET /agent/conversations/{conversation_id} — Read the state of a conversation - POST /agent/conversations/{conversation_id}/messages — Send a message to the Kelki Agent ## POST `/agent/conversations` Start a conversation with the Kelki Agent Conversation tied to the account and the mode. Forgotten 2 hours after the last message. Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `agent`). ### Parameters | Name | In | Required | Type | Description | | `Idempotency-Key` | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern `^[A-Za-z0-9_\-]{8,64}$` | ### Request body `application/json` — ConversationCreate ``` { "country": "FR", "lang": "fr", "first_message": "Le volet roulant du salon est bloqué en position basse.", "reference": "resa-2026-0042" } ``` ### Responses | Code | Description | Content | | `201` | Conversation created, with the agent's first reply. | `application/json` Conversation | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `403` | Missing scope, account not enabled for live, country not open, account suspended. | `application/problem+json` Problem | | `429` | Rate or quota exceeded. | `application/problem+json` Problem | | `503` | Service paused or under maintenance (e.g. agent paused, live creation suspended). | `application/problem+json` Problem | ### Response example ``` { "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}` Read the state of a conversation Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `agent`). ### Parameters | Name | In | Required | Type | Description | | `conversation_id` | path | yes | string | pattern `^conv_[0-9A-Za-z]{20,40}$` | ### Responses | Code | Description | Content | | `200` | State of the conversation. | `application/json` Conversation | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | ## POST `/agent/conversations/{conversation_id}/messages` Send a message to the Kelki Agent A message contains only one of: `text` (free text, goes through the model), `choice` (value of a button), `data` (structured fields), `consent` (the person's consent at the `recap` step). `consent: true` creates a draft then starts the e-mail confirmation, exactly like `POST /requests` + `POST /requests/{id}/confirmation` (scope `requests.write` also required). Authentication: API key (`Authorization: Bearer kk_…`) or OAuth 2.0 token (scope `agent`) or OAuth 2.0 token (scope `agent`, `requests.write`). ### Parameters | Name | In | Required | Type | Description | | `conversation_id` | path | yes | string | pattern `^conv_[0-9A-Za-z]{20,40}$` | | `Idempotency-Key` | header | yes | string | 8 to 64 characters, unique per operation. Same key + same body within 24 h = same response. pattern `^[A-Za-z0-9_\-]{8,64}$` | ### Request body `application/json` — AgentMessage (required) ``` { "choice": "metier:volets-roulants" } ``` ### Responses | Code | Description | Content | | `200` | The agent's reply. | `application/json` Conversation | | `401` | Missing, invalid, expired or revoked credentials. | `application/problem+json` Problem | | `403` | Missing scope, account not enabled for live, country not open, account suspended. | `application/problem+json` Problem | | `404` | Unknown resource, or one belonging to another account or another mode (same response). | `application/problem+json` Problem | | `422` | Value refused by the form's rules (closed lists, place, contact details, consent, anti-abuse limits). | `application/problem+json` Problem | | `429` | Rate or quota exceeded. | `application/problem+json` Problem | | `503` | Service paused or under maintenance (e.g. agent paused, live creation suspended). | `application/problem+json` Problem | ## Schemas ### `ConversationCreate` | Field | Type | Required | Description | | `country` | CountryCode | no | | | `lang` | LanguageCode | no | | | `first_message` | string | no | max. 600 chars | | `reference` | PartnerReference | no | | | `end_user_ref` | string | no | pattern `^[A-Za-z0-9_\-]{6,64}$` | ### `Conversation` | Field | Type | Required | Description | | `id` | string | yes | | | `object` | string | yes | value: `conversation` | | `mode` | string | yes | values: `test`, `live` | | `step` | string | yes | values: `metier`, `metier_choix`, `besoin`, `besoin_libre`, `delai`, `lieu`, `lieu_choix`, `coordonnees`, `recap`, `envoyee` | | `text` | string | yes | The agent's text; any e-mail or number in it is masked. | | `choices` | array of Choice | yes | | | `recap` | string | null | no | Masked summary (recap step). | | `consent` | ConsentText or null | no | | | `request_id` | string | null | no | Request created after `consent: true`. | | `fallback` | string | null | no | `form`: the agent hands over (budget, model failure); continue with POST /requests. values: `form`, `` | | `expires_at` | string (date-time) | yes | | ### `Problem` Problem details (RFC 9457), with extension members. | Field | Type | Required | Description | | `type` | string (uri) | yes | Stable URI of the problem type; it leads to its documentation. | | `title` | string | yes | | | `status` | integer | yes | min. 400 · max. 599 | | `detail` | string | no | | | `instance` | string (uri-reference) | no | | | `code` | string | yes | Stable, machine-readable code. values: `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 | yes | | | `errors` | array of FieldError | no | | ### `AgentMessage` | Field | Type | Required | Description | | `text` | string | no | max. 600 chars | | `choice` | string | no | max. 200 chars | | `data` | object | no | | | `consent` | boolean | no | value: `True` | | `consent_text_version` | string | no | pattern `^v\d{4}-\d{2}-\d{2}$` | ### `CountryCode` Type: string — pattern `^[A-Z]{2}$` · default `"FR"` ### `LanguageCode` Type: string — pattern `^[a-z]{2}$` ### `PartnerReference` Your reference (e.g. booking number). No personal data. Returned in webhooks. Type: string — pattern `^[A-Za-z0-9._:\-]{1,64}$` ### `Choice` | Field | Type | Required | Description | | `value` | string | yes | | | `label` | string | yes | | | `hint` | string | no | | ### `ConsentText` | Field | Type | Required | Description | | `version` | string | yes | pattern `^v\d{4}-\d{2}-\d{2}$` | | `lang` | LanguageCode | yes | | | `text` | string | yes | To display word for word, next to a checkbox left unticked by default. | | `valid_from` | string (date) | yes | | ### `FieldError` | Field | Type | Required | Description | | `pointer` | string | yes | JSON Pointer (RFC 6901) of the field at fault. | | `detail` | string | yes | | | `allowed` | array of string | no | Accepted values, when the list is closed. | ## About this page - URL : https://kelki.ai/developers/en/reference/agent/ - Language : en - fr : https://kelki.ai/developers/fr/reference/agent/ - en : https://kelki.ai/developers/en/reference/agent/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt