Server-API (REST v1) en MCP

De REST-interface voor uw backend: API-sleutels, scopes, verzoeklimieten, antwoorden en fouten, paginering, endpoints voor projecten, gesprekken, berichten, bezoekers, gebeurtenissen, regels en hooks, en MCP.

De server-API is bedoeld voor uw backend, niet voor de browser: CORS wordt niet toegestaan en een API-sleutel hoort nooit in een webpagina of app.

Basis

Basis: https://reactive.chat/v1/
Versie: in het pad (v1). Binnen v1 worden velden toegevoegd maar niet verwijderd; negeer onbekende velden.
Formaat: JSON, UTF-8. Tijdstippen als ISO 8601 in UTC (2026-10-21T08:15:30.123Z). ID’s worden als strings uitgevoerd ("id":"123").
Antwoordheaders: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
Een pad dat niet bestaat, geeft een 404-pagina terug (geen JSON).

API-sleutels

In uw account onder API-sleutels (/app/api-keys, alleen eigenaren en beheerders). U geeft een naam en een scope op; de sleutel (rc_live_ + 48 tekens) wordt precies één keer getoond en wij bewaren alleen een hash.

Scopes:

alleen lezen — read
lezen en schrijven — read, write
lezen + bezoekersgegevens — read, besucherdaten:lesen
lezen, schrijven + bezoekersgegevens — read, write, besucherdaten:lesen
alleen import van klantgegevens — kundendaten:schreiben (Klantgegevens)

Een sleutel hoort bij precies één werkruimte; geen pad of parameter selecteert een andere. De sleutel wordt ongeldig als u deze intrekt of als de persoon die deze heeft aangemaakt geen eigenaar of beheerder van de werkruimte meer is. Er is geen vervaldatum — vernieuw zelf (nieuwe sleutel aanmaken, omschakelen, oude intrekken).

Verzenden:

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

De header X-Api-Key: rc_live_... is gelijkwaardig (deze wordt alleen gelezen als er geen Authorization: Bearer is).

Verzoeklimieten

120 verzoeken per minuut en sleutel, een vast tijdvenster dat op de volle minuut begint. Elk verzoek telt mee, ook een afgewezen verzoek.
Elk antwoord bevat X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (seconden tot het volgende venster, geen tijdstempel).
Daarboven: 429 rate_limited met Retry-After.
Na 60 mislukte authenticaties per adres binnen 15 minuten: 429 met Retry-After: 900.

Antwoordformaat

{ "data": { ... } }

Lijsten:

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

Paginering: limit (standaard 25, maximaal 100) en een cursor — before_id voor lijsten met het nieuwste eerst, after_id voor lijsten met het oudste eerst. next is alleen aanwezig als has_more true is. Er is geen totaalaantal.

Bodies van POST/PUT: alleen Content-Type: application/json (anders 415), maximaal 65.536 bytes (anders 413), een JSON-object met maximaal 32 niveaus.

Foutformaat

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

message is een vaste Engelse zin voor ontwikkelaars. Afhankelijk van de fout worden param, required_scope, max, allowed en reason toegevoegd. Dit zijn alle codes:

400 bad_request, bad_json
401 auth_required (geen sleutel), auth_failed (ongeldig of ingetrokken)
402 plan_required
403 insufficient_scope, workspace_inactive
404 not_found, conversation_not_found
405 method_not_allowed (met Allow)
409 conversation_closed, import_disabled
413 payload_too_large
415 unsupported_media_type
422 msg_too_long (met max)
429 rate_limited
500 internal, 501 not_implemented, 503 unavailable

Endpoints

Account

GET /v1/me — geen specifieke scope vereist. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Geschikt om een sleutel te controleren.

Projecten (read)

GET /v1/projects — limit, before_id. Per project: id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
GET /v1/projects/{id}

Gesprekken (read)

GET /v1/conversations — nieuwste eerst. Filters project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Per gesprek: 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}

Berichten

GET /v1/conversations/{id}/messages (read) — oudste eerst, after_id, limit. Per bericht: id, conversation_id, client_ulid, direction (in naar de bezoeker, out van de bezoeker), author_type, author_id, kind, body, redacted, delivery_state, created_at; indien aanwezig card, cards, form, form_reply, action, quick_replies, quick_reply_of.
GET /v1/messages (read) — alle berichten van de werkruimte als stream, conversation_id optioneel, after_id, limit. Om berichten zonder webhooks op te halen.
POST /v1/conversations/{id}/messages (write) — een bericht in een gesprek schrijven:

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 (string, verplicht, maximaal 4000 tekens)
author_type (agent | bot | system, standaard agent) — niet namens de bezoeker
client_ulid (ULID, optioneel) — voor idempotentie: dezelfde ID opnieuw geeft 200 met het bestaande bericht terug in plaats van een tweede bericht (de eerste keer 201).
409 conversation_closed bij een gesloten gesprek, 422 msg_too_long.
Let op: zo geschreven berichten worden opgeslagen, maar bereiken een momenteel geopende widget niet direct — pas bij de volgende synchronisatie. Gebruik voor liveantwoorden de MCP-tool nachricht_senden (hieronder).

Bezoekers (read)

GET /v1/visitors — livebezoekerslijst: project_id, online (0/1), limit. Per bezoeker onder andere online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (met UTM), device, country, language, returning, conversation. Daarnaast disabled_project_ids voor projecten waarin de bezoekerslijst is uitgeschakeld.

Gebeurtenissen

GET /v1/events (read) — project_id, type, source (mp, rc, integration), after_id, limit. Per gebeurtenis id, project_id, source, type, session_id, conversation_id, payload, created_at.
POST /v1/events (write) — een eigen gebeurtenis uit uw systeem aan een sessie of gesprek koppelen:

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

type moet passen bij ^[a-z][a-z0-9_.:-]{0,47}$, payload maximaal 8192 bytes, ts in milliseconden (maximaal 7 dagen oud, maximaal 5 minuten in de toekomst). source is altijd integration. Antwoord 201.

Regels (read)

GET /v1/rules — project_id. Per project source (custom of default) en rules. Alleen lezen; regels bewerkt u onder Aanpassing.

Hooks — zie Webhooks: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Klantgegevens — zie Klantgegevens: PUT en DELETE /v1/kundendaten/{user_id}.

Voorbeeld: open gesprekken ophalen

<?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);

MCP-server

Voor AI-tools die het Model Context Protocol ondersteunen, is er een MCP-server onder hetzelfde basisadres:

Adres: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, zonder sessiestatus, geen batching). Het exacte adres staat op de pagina API-sleutels.
Authenticatie: dezelfde API-sleutel als Authorization: Bearer; dezelfde verzoeklimiet.
Protocolversies: 2026-07-28 (met server/discover; de headers MCP-Protocol-Version, Mcp-Method en bij tools/call ook Mcp-Name zijn vereist), plus 2025-11-25, 2025-06-18 en 2025-03-26 (met initialize).
Alleen servers: verzoeken met een browser-Origin worden met 403 afgewezen.

Tools (tools/list toont alleen de tools die uw sleutel mag gebruiken):

kb_suchen (read) — projekt, frage (maximaal 500 tekens), n (1–10, standaard 5). Doorzoekt de kennisbank; maximaal 20 zoekopdrachten per minuut en sleutel.
gespraeche_auflisten (read) — projekt, status, seit (ISO-tijdstip), limit (maximaal 100), vor_id.
gespraech_lesen (read) — id, limit (maximaal 200, standaard 100).
nachricht_senden (write) — gespraech, text (maximaal 4000 tekens), optioneel als (e-mail van een medewerker die in het project mag antwoorden). Levert direct af als medewerkersbericht; de assistent zwijgt daarna in dit gesprek.
wissensluecken (read) — projekt, stand (offen, erledigt, ignoriert), limit (maximaal 60).

Zonder besucherdaten:lesen worden naam, e-mail en telefoonnummer van bezoekers ingekort en persoonsgegevens in teksten gemaskeerd. Toolfouten komen als isError: true met identificatoren zoals project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Voorbeeldconfiguratie voor een MCP-client:

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

MCP en de bezoekerslijst zijn nieuwe functies; ze kunnen per project zijn uitgeschakeld (het betreffende project meldt dan disabled).

Wat niet bestaat

Geen persoonlijke medewerkerstokens en geen testsleutels; alle sleutels zijn rc_live_-werkruimtesleutels.
Geen endpoints om gesprekken aan te maken, namens bezoekers te schrijven of projectinstellingen, regels of de kennisbank te wijzigen.
Geen CORS — de API is niet bedoeld voor browsers.

Volgende: Webhooks · Integraties en kanalen

Huling na-update: 2026-10-25