Till startsidan

Server-API (REST v1) och MCP

REST-gränssnittet i reactive.chat för din backend – API-nycklar och omfattningar, anropsbegränsning, svars- och felformat, sidindelning, alla slutpunkter för projekt, konversationer, meddelanden, besökare, händelser, regler och hooks – samt MCP-servern för AI-verktyg.

Server-API:et är avsett för din backend, inte för webbläsaren: det tillåter inte CORS och en API-nyckel hör aldrig hemma på en webbsida eller i en app.

Grunder

Bas: https://reactive.chat/v1/
Version: i sökvägen (v1). Inom v1 läggs fält till men inga tas bort; ignorera okända fält.
Format: JSON, UTF-8. Tider som ISO 8601 i UTC (2026-10-21T08:15:30.123Z). ID:n returneras som strängar ("id":"123").
Svarshuvuden: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
En sökväg som inte finns returnerar en 404-sida (inte JSON).

API-nycklar

I kontot under API-nycklar (/app/api-keys, bara ägare och administratörer). Du anger namn och omfattning; nyckeln (rc_live_ + 48 tecken) visas exakt en gång och vi lagrar bara en hash.

Omfattningar:

endast läsa – read
läsa och skriva – read, write
läsa + besökaruppgifter – read, besucherdaten:lesen
läsa, skriva + besökaruppgifter – read, write, besucherdaten:lesen
endast import av kunddata – kundendaten:schreiben (Kunddata)

En nyckel tillhör exakt en arbetsyta; ingen sökväg eller parameter väljer en annan. Den blir ogiltig när du återkallar den eller när personen som skapade den inte längre är ägare eller administratör i arbetsytan. Inget utgångsdatum finns – rotera själv (skapa en ny, byt, återkalla den gamla).

Skicka:

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

Huvudet X-Api-Key: rc_live_... är likvärdigt (läses bara om Authorization: Bearer saknas).

Anropsbegränsning

120 anrop per minut och nyckel, fast tidsfönster vid hel minut. Varje anrop räknas, även ett avvisat.
Varje svar innehåller X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset (sekunder till nästa fönster, inte en tidsstämpel).
Över gränsen: 429 rate_limited med Retry-After.
Efter 60 misslyckade autentiseringar per adress inom 15 minuter: 429 med Retry-After: 900.

Svarsformat

{ "data": { ... } }

Listor:

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

Sidindelning: limit (standard 25, högst 100) och en markör – before_id för listor med ”nyast först”, after_id för ”äldst först”. next finns bara om has_more är true. Det finns inget totalt antal.

Kroppar för POST/PUT: endast Content-Type: application/json (annars 415), högst 65 536 byte (annars 413), ett JSON-objekt med högst 32 nivåer.

Felformat

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

message är en fast engelsk mening för utvecklare. Beroende på fel tillkommer param, required_scope, max, allowed, reason. Koderna är uttömmande:

400 bad_request, bad_json
401 auth_required (ingen nyckel), auth_failed (ogiltig eller återkallad)
402 plan_required
403 insufficient_scope, workspace_inactive
404 not_found, conversation_not_found
405 method_not_allowed (med Allow)
409 conversation_closed, import_disabled
413 payload_too_large
415 unsupported_media_type
422 msg_too_long (med max)
429 rate_limited
500 internal, 501 not_implemented, 503 unavailable

Slutpunkter

Konto

GET /v1/me – ingen särskild omfattning krävs. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Bra för att kontrollera en nyckel.

Projekt (read)

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

Konversationer (read)

GET /v1/conversations – nyast först. Filter project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Per konversation: 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}

Meddelanden

GET /v1/conversations/{id}/messages (read) – äldst först, after_id, limit. Per meddelande: id, conversation_id, client_ulid, direction (in till besökaren, out från besökaren), author_type, author_id, kind, body, redacted, delivery_state, created_at; där de finns card, cards, form, form_reply, action, quick_replies, quick_reply_of.
GET /v1/messages (read) – arbetsytans alla meddelanden som en ström, conversation_id valfritt, after_id, limit. För insamling utan webhookar.
POST /v1/conversations/{id}/messages (write) – skriv ett meddelande i en konversation:

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 (sträng, obligatorisk, högst 4000 tecken)
author_type (agent | bot | system, standard agent) – inte för besökarens räkning
client_ulid (ULID, valfritt) – för idempotens: samma ID igen returnerar 200 med det befintliga meddelandet i stället för ett andra (201 första gången).
409 conversation_closed för en avslutad konversation, 422 msg_too_long.
Obs: meddelanden som skrivs så här lagras men når inte en widget som är öppen just nu omedelbart – först vid nästa synkronisering. För livesvar använder du MCP-verktyget nachricht_senden (nedan).

Besökare (read)

GET /v1/visitors – livebesökarlista: project_id, online (0/1), limit. Per besökare bland annat online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (med UTM), device, country, language, returning, conversation. Dessutom disabled_project_ids för projekt där besökarlistan är avstängd.

Händelser

GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. Per händelse id, project_id, source, type, session_id, conversation_id, payload, created_at.
POST /v1/events (write) – koppla en egen händelse från ditt system till en session eller konversation:

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

type som matchar ^[a-z][a-z0-9_.:-]{0,47}$, payload högst 8192 byte, ts i millisekunder (högst 7 dagar gammal, högst 5 minuter framåt). source är alltid integration. Svar 201.

Regler (read)

GET /v1/rules – project_id. Per projekt source (custom eller default) och rules. Endast läsning; du redigerar regler under Anpassning.

Hooks – se Webhookar: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Kunddata – se Kunddata: PUT och DELETE /v1/kundendaten/{user_id}.

Exempel: samla in öppna konversationer

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

För AI-verktyg som använder Model Context Protocol finns en MCP-server under samma bas:

Adress: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, tillståndslöst, ingen batchning). Den exakta adressen visas på sidan API-nycklar.
Autentisering: samma API-nyckel som Authorization: Bearer; samma anropsgräns.
Protokollversioner: 2026-07-28 (med server/discover; huvudena MCP-Protocol-Version, Mcp-Method och för tools/call även Mcp-Name krävs) samt 2025-11-25, 2025-06-18 och 2025-03-26 (med initialize).
Endast server: anrop med ett webbläsar-Origin avvisas med 403.

Verktyg (tools/list visar bara dem som nyckeln får använda):

kb_suchen (read) – projekt, frage (högst 500 tecken), n (1–10, standard 5). Söker i kunskapsbasen; högst 20 sökningar per minut och nyckel.
gespraeche_auflisten (read) – projekt, status, seit (ISO-tid), limit (högst 100), vor_id.
gespraech_lesen (read) – id, limit (högst 200, standard 100).
nachricht_senden (write) – gespraech, text (högst 4000 tecken), valfritt als (e-postadress till en agent som får svara i projektet). Levererar omedelbart som ett agentmeddelande; assistenten tystnar i konversationen.
wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (högst 60).

Utan besucherdaten:lesen förkortas besökarnas namn, e-post och telefon och personuppgifter i texter maskeras. Verktygsfel kommer som isError: true med identifierare som project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Exempelpost för en MCP-klient:

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

MCP och besökarlistan är nya funktioner; de kan vara avstängda per projekt (det berörda projektet rapporterar då disabled).

Vad som inte finns

Inga personliga agenttoken och inga testnycklar; alla nycklar är arbetsytenycklar av typen rc_live_.
Inga slutpunkter för att skapa konversationer, skriva för besökares räkning eller ändra projektinställningar, regler eller kunskapsbasen.
Ingen CORS – API:et är inte avsett för webbläsare.

Nästa: Webhookar · Integrationer och kanaler

Senast uppdaterad: 2026-10-25