Serverové API (REST v1) a MCP

Serverové API je určené pro váš backend, ne pro prohlížeč: nepovoluje CORS a klíč API nikdy nepatří na webovou stránku ani do aplikace.

Základy

• Základní adresa: https://reactive.chat/v1/
• Verze: v cestě (v1). V rámci v1 se pole přidávají, ale žádná se neodstraňují; neznámá pole ignorujte.
• Formát: JSON, UTF-8. Časy jako ISO 8601 v UTC (2026-10-21T08:15:30.123Z). ID se vypisují jako řetězce ("id":"123").
• Hlavičky odpovědi: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
• Neexistující cesta vrací stránku 404 (ne JSON).

Klíče API

V účtu pod Klíče API (/app/api-keys, pouze vlastníci a administrátoři). Zadáte název a rozsah; klíč (rc_live_ + 48 znaků) se zobrazí právě jednou a ukládáme pouze hash.

Rozsahy:

• jen čtení – read
• čtení a zápis – read, write
• čtení + údaje návštěvníků – read, besucherdaten:lesen
• čtení, zápis + údaje návštěvníků – read, write, besucherdaten:lesen
• jen import zákaznických dat – kundendaten:schreiben (Zákaznická data)

Klíč patří právě jednomu pracovnímu prostoru; žádná cesta ani parametr nevybírá jiný. Zneplatní se při odvolání nebo když osoba, která ho vytvořila, už není vlastníkem ani administrátorem pracovního prostoru. Datum vypršení neexistuje — rotaci provádějte sami (vytvořte nový, přepněte, odvolejte starý).

Odesílání:

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

Hlavička X-Api-Key: rc_live_... je rovnocenná (čte se pouze tehdy, když chybí Authorization: Bearer).

Omezení počtu požadavků

• 120 požadavků za minutu na klíč, pevné okno zarovnané na celou minutu. Počítá se každý požadavek včetně odmítnutého.
• Každá odpověď nese X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (sekundy do dalšího okna, nikoli časové razítko).
• Nad limitem: 429 rate_limited s Retry-After.
• Po 60 neúspěšných ověřeních z jedné adresy během 15 minut: 429 s Retry-After: 900.

Formát odpovědi

{ "data": { ... } }

Seznamy:

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

Stránkování: limit (výchozí 25, nejvýše 100) a kurzor — before_id pro seznamy „nejnovější první“, after_id pro „nejstarší první“. next je přítomné pouze tehdy, když je has_more true. Celkový počet není k dispozici.

Těla POST/PUT: pouze Content-Type: application/json (jinak 415), nejvýše 65 536 bajtů (jinak 413), objekt JSON s nejvýše 32 úrovněmi.

Formát chyb

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

message je pevná anglická věta pro vývojáře. Podle chyby se přidávají param, required_scope, max, allowed, reason. Výčet kódů je úplný:

• 400 bad_request, bad_json
• 401 auth_required (chybí klíč), auth_failed (neplatný nebo odvolaný)
• 402 plan_required
• 403 insufficient_scope, workspace_inactive
• 404 not_found, conversation_not_found
• 405 method_not_allowed (s Allow)
• 409 conversation_closed, import_disabled
• 413 payload_too_large
• 415 unsupported_media_type
• 422 msg_too_long (s max)
• 429 rate_limited
• 500 internal, 501 not_implemented, 503 unavailable

Endpointy

Účet

• GET /v1/me – bez požadavku na konkrétní rozsah. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Vhodné pro ověření klíče.

Projekty (read)

• GET /v1/projects – limit, before_id. U každého projektu: id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
• GET /v1/projects/{id}

Konverzace (read)

• GET /v1/conversations – nejnovější první. Filtry project_id, status (open, bot, waiting, assigned, closed), limit, before_id. U každé konverzace: 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}

Zprávy

• GET /v1/conversations/{id}/messages (read) – nejstarší první, after_id, limit. U každé zprávy: id, conversation_id, client_ulid, direction (in k návštěvníkovi, out od návštěvníka), author_type, author_id, kind, body, redacted, delivery_state, created_at; pokud existují, card, cards, form, form_reply, action, quick_replies, quick_reply_of.
• GET /v1/messages (read) – všechny zprávy pracovního prostoru jako stream, volitelně conversation_id, after_id, limit. Pro sběr bez webhooků.
• POST /v1/conversations/{id}/messages (write) – zapsat zprávu do konverzace:

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 (řetězec, povinný, nejvýše 4000 znaků)
• author_type (agent | bot | system, výchozí agent) – ne jménem návštěvníka
• client_ulid (ULID, volitelné) – pro idempotenci: stejné ID znovu vrátí 200 s existující zprávou místo druhé (při prvním volání 201).
• 409 conversation_closed u uzavřené konverzace, 422 msg_too_long.
• Pozor: takto zapsané zprávy se ukládají, ale do právě otevřeného widgetu nedojdou okamžitě — až při další synchronizaci. Pro živé odpovědi použijte nástroj MCP nachricht_senden (níže).

Návštěvníci (read)

• GET /v1/visitors – živý seznam návštěvníků: project_id, online (0/1), limit. U každého návštěvníka mimo jiné online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (s UTM), device, country, language, returning, conversation. Navíc disabled_project_ids pro projekty, ve kterých je seznam návštěvníků vypnutý.

Události

• GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. U každé události id, project_id, source, type, session_id, conversation_id, payload, created_at.
• POST /v1/events (write) – připojit vlastní událost z vašeho systému k relaci nebo konverzaci:

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

type odpovídá ^[a-z][a-z0-9_.:-]{0,47}$, payload nejvýše 8192 bajtů, ts v milisekundách (nejvýše 7 dnů staré, nejvýše 5 minut dopředu). source je vždy integration. Odpověď 201.

Pravidla (read)

• GET /v1/rules – project_id. U každého projektu source (custom nebo default) a rules. Pouze pro čtení; pravidla upravujete v části Přizpůsobení.

Hooky – viz Webhooky: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Zákaznická data – viz Zákaznická data: PUT a DELETE /v1/kundendaten/{user_id}.

Příklad: sběr otevřených konverzací

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

Server MCP

Pro nástroje AI podporující Model Context Protocol existuje server MCP pod stejnou základní adresou:

• Adresa: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, bezstavové, bez dávkování). Přesná adresa se zobrazuje na stránce Klíče API.
• Ověření: stejný klíč API jako Authorization: Bearer; stejný limit požadavků.
• Verze protokolu: 2026-07-28 (se server/discover; povinné jsou hlavičky MCP-Protocol-Version, Mcp-Method a u tools/call také Mcp-Name) a 2025-11-25, 2025-06-18 a 2025-03-26 (s initialize).
• Pouze server: požadavky s prohlížečovou hlavičkou Origin se odmítají s 403.

Nástroje (tools/list zobrazuje jen ty, které smí váš klíč používat):

• kb_suchen (read) – projekt, frage (nejvýše 500 znaků), n (1–10, výchozí 5). Prohledává znalostní bázi; nejvýše 20 hledání za minutu na klíč.
• gespraeche_auflisten (read) – projekt, status, seit (čas ISO), limit (nejvýše 100), vor_id.
• gespraech_lesen (read) – id, limit (nejvýše 200, výchozí 100).
• nachricht_senden (write) – gespraech, text (nejvýše 4000 znaků), volitelně als (e-mail operátora, který smí v projektu odpovídat). Doručuje okamžitě jako zprávu operátora; asistent v této konverzaci ztichne.
• wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (nejvýše 60).

Bez besucherdaten:lesen se jméno, e-mail a telefon návštěvníků zkracují a osobní údaje v textech maskují. Chyby nástrojů přicházejí jako isError: true s identifikátory jako project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Vzorový záznam pro klienta MCP:

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

MCP a seznam návštěvníků jsou nové funkce; lze je vypnout pro jednotlivé projekty (dotčený projekt pak hlásí disabled).

Co neexistuje

• Žádné osobní tokeny operátorů ani testovací klíče; všechny klíče jsou klíče pracovního prostoru rc_live_.
• Žádné endpointy pro vytváření konverzací, psaní jménem návštěvníků nebo změnu nastavení projektu, pravidel či znalostní báze.
• Žádné CORS — API není určené pro prohlížeče.

Dále: Webhooky · Integrace a kanály