API serveur (REST v1) et MCP

L’API serveur est destinée à votre backend, pas au navigateur : elle n’autorise pas CORS, et une clé d’API ne doit jamais figurer dans une page web ou une application.

Principes

• Base : https://reactive.chat/v1/
• Version : dans le chemin (v1). Dans v1, des champs sont ajoutés mais aucun n’est supprimé ; ignorez les champs inconnus.
• Format : JSON, UTF-8. Dates au format ISO 8601 en UTC (2026-10-21T08:15:30.123Z). Les identifiants sont renvoyés comme chaînes ("id":"123").
• En-têtes de réponse : Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
• Un chemin inexistant renvoie une page 404 (pas du JSON).

Clés d’API

Dans votre compte, sous Clés d’API (/app/api-keys, propriétaires et administrateurs uniquement). Attribuez un nom et une portée ; la clé (rc_live_ + 48 caractères) n’est affichée qu’une seule fois et nous n’en conservons qu’un hachage.

Portées :

• lecture seule – read
• lecture et écriture – read, write
• lecture + données visiteurs – read, besucherdaten:lesen
• lecture, écriture + données visiteurs – read, write, besucherdaten:lesen
• import de données clients uniquement – kundendaten:schreiben (Données clients)

Une clé appartient exactement à un espace de travail ; aucun chemin ni paramètre n’en sélectionne un autre. Elle devient invalide si vous la révoquez ou si son créateur n’est plus propriétaire ou administrateur de l’espace de travail. Elle n’a pas de date d’expiration : effectuez vous-même la rotation (créer une nouvelle clé, l’utiliser, révoquer l’ancienne).

Envoi :

curl https://reactive.chat/v1/me -H "Authorization: Bearer rc_live_..."

L’en-tête X-Api-Key: rc_live_... est équivalent (il n’est lu qu’en l’absence de Authorization: Bearer).

Limitation de fréquence

• 120 requêtes par minute et par clé, avec fenêtre fixe alignée sur la minute entière. Chaque requête compte, même rejetée.
• Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant la prochaine fenêtre, pas un horodatage).
• Au-delà : 429 rate_limited avec Retry-After.
• Après 60 échecs d’authentification par adresse en 15 minutes : 429 avec Retry-After: 900.

Format de réponse

{ "data": { ... } }

Listes :

{ "data": [ ... ], "has_more": true, "next": { "before_id": "812" } }

Pagination : limit (25 par défaut, 100 maximum) et un curseur : before_id pour les listes des plus récentes aux plus anciennes, after_id pour l’ordre inverse. next n’est présent que si has_more vaut true. Aucun nombre total n’est fourni.

Corps des POST/PUT : uniquement Content-Type: application/json (sinon 415), au maximum 65 536 octets (sinon 413), un objet JSON de 32 niveaux maximum.

Format d’erreur

{ "error": { "code": "insufficient_scope", "message": "...", "required_scope": "write" } }

message est une phrase anglaise fixe destinée aux développeurs. Selon l’erreur, param, required_scope, max, allowed, reason sont ajoutés. Voici la liste exhaustive des codes :

• 400 bad_request, bad_json
• 401 auth_required (aucune clé), auth_failed (invalide ou révoquée)
• 402 plan_required
• 403 insufficient_scope, workspace_inactive
• 404 not_found, conversation_not_found
• 405 method_not_allowed (avec Allow)
• 409 conversation_closed, import_disabled
• 413 payload_too_large
• 415 unsupported_media_type
• 422 msg_too_long (avec max)
• 429 rate_limited
• 500 internal, 501 not_implemented, 503 unavailable

Points de terminaison

Compte

• GET /v1/me – aucune portée particulière requise. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Utile pour vérifier une clé.

Projets (read)

• GET /v1/projects – limit, before_id. Par projet : id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
• GET /v1/projects/{id}

Conversations (read)

• GET /v1/conversations – les plus récentes en premier. Filtres : project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Par conversation : id, project_id, status, channel, visitor_id, session_id, assignee_id, csat_score, handoff_reason, created_at, updated_at, closed_at.
• GET /v1/conversations/{id}

Messages

• GET /v1/conversations/{id}/messages (read) – les plus anciens en premier, after_id, limit. Par message : id, conversation_id, client_ulid, direction (in vers le visiteur, out depuis le visiteur), author_type, author_id, kind, body, redacted, delivery_state, created_at ; si présents : card, cards, form, form_reply, action, quick_replies, quick_reply_of.
• GET /v1/messages (read) – tous les messages de l’espace de travail sous forme de flux, conversation_id facultatif, after_id, limit. Pour collecter sans webhooks.
• POST /v1/conversations/{id}/messages (write) – écrire un message dans une conversation :

curl -X POST https://reactive.chat/v1/conversations/815/messages \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Your return has arrived.","author_type":"agent","client_ulid":"01JAB3C4D5E6F7G8H9JKMNPQRS"}'

• body (chaîne, obligatoire, 4000 caractères maximum)
• author_type (agent | bot | system, agent par défaut) – pas au nom du visiteur
• client_ulid (ULID, facultatif) – pour l’idempotence : réutiliser le même identifiant renvoie 200 avec le message existant au lieu d’en créer un second (201 la première fois).
• 409 conversation_closed pour une conversation fermée, 422 msg_too_long.
• Remarque : ces messages sont enregistrés, mais ne parviennent pas immédiatement à un widget actuellement ouvert, seulement à la prochaine synchronisation. Pour une réponse en direct, utilisez l’outil MCP nachricht_senden (ci-dessous).

Visiteurs (read)

• GET /v1/visitors – liste des visiteurs en direct : project_id, online (0/1), limit. Par visiteur, notamment : online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (avec UTM), device, country, language, returning, conversation. Aussi disabled_project_ids pour les projets où la liste des visiteurs est désactivée.

Événements

• GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. Par événement : id, project_id, source, type, session_id, conversation_id, payload, created_at.
• POST /v1/events (write) – rattacher un événement de votre système à une session ou une conversation :

{ "project_id": "123", "type": "bestellung.storniert",
  "session_id": "s_...", "conversation_id": "01JAB...",
  "payload": { "nummer": "2026-0815" }, "ts": 1792503600000 }

type conforme à ^[a-z][a-z0-9_.:-]{0,47}$, payload de 8192 octets maximum, ts en millisecondes (au plus 7 jours dans le passé, 5 minutes dans le futur). source vaut toujours integration. Réponse 201.

Règles (read)

• GET /v1/rules – project_id. Par projet, source (custom ou default) et rules. Lecture seule ; les règles se modifient sous Personnalisation.

Hooks – voir Webhooks : GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Données clients – voir Données clients : PUT et DELETE /v1/kundendaten/{user_id}.

Exemple : collecter les conversations ouvertes

<?php
$key = getenv('RC_API_KEY');
$url = 'https://reactive.chat/v1/conversations?status=waiting&limit=100';
do {
    $ch = curl_init($url);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key]]);
    $antwort = json_decode((string) curl_exec($ch), true);
    $status  = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($status === 429) { sleep(60); continue; }
    foreach ($antwort['data'] as $g) { echo $g['id'], ' ', $g['created_at'], "\n"; }
    $url = !empty($antwort['has_more'])
        ? 'https://reactive.chat/v1/conversations?status=waiting&limit=100&before_id=' . $antwort['next']['before_id']
        : null;
} while ($url);

Serveur MCP

Pour les outils IA compatibles avec le Model Context Protocol, un serveur MCP est disponible sous la même base :

• Adresse : POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, sans état ni traitement par lots). L’adresse exacte figure sur la page Clés d’API.
• Authentification : la même clé d’API comme Authorization: Bearer ; la même limite de fréquence.
• Versions du protocole : 2026-07-28 (avec server/discover ; en-têtes MCP-Protocol-Version, Mcp-Method et, pour tools/call, Mcp-Name requis), ainsi que 2025-11-25, 2025-06-18 et 2025-03-26 (avec initialize).
• Serveur uniquement : les requêtes comportant un Origin de navigateur sont rejetées avec 403.

Outils (tools/list n’affiche que ceux autorisés par votre clé) :

• kb_suchen (read) – projekt, frage (500 caractères maximum), n (1–10, 5 par défaut). Recherche dans la base de connaissances ; au maximum 20 recherches par minute et par clé.
• gespraeche_auflisten (read) – projekt, status, seit (date ISO), limit (100 maximum), vor_id.
• gespraech_lesen (read) – id, limit (200 maximum, 100 par défaut).
• nachricht_senden (write) – gespraech, text (4000 caractères maximum), facultativement als (e-mail d’un agent autorisé à répondre dans le projet). Livre immédiatement un message d’agent ; l’assistant cesse de répondre dans cette conversation.
• wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (60 maximum).

Sans besucherdaten:lesen, le nom, l’e-mail et le téléphone des visiteurs sont tronqués et les données personnelles des textes sont masquées. Les erreurs d’outil prennent la forme isError: true, avec des identifiants tels que project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Exemple de configuration d’un client MCP :

{
  "mcpServers": {
    "reactive-chat": {
      "url": "https://reactive.chat/v1/mcp",
      "headers": { "Authorization": "Bearer rc_live_..." }
    }
  }
}

MCP et la liste des visiteurs sont de nouvelles fonctions ; elles peuvent être désactivées par projet (le projet concerné indique alors disabled).

Ce qui n’existe pas

• Aucun jeton personnel d’agent ni clé de test ; toutes les clés sont des clés d’espace de travail rc_live_.
• Aucun point de terminaison pour créer des conversations, écrire au nom des visiteurs ou modifier les réglages des projets, les règles ou la base de connaissances.
• Pas de CORS : l’API n’est pas destinée aux navigateurs.

Suite : Webhooks · Intégrations et canaux