API serwera (REST v1) i MCP

API serwera jest przeznaczone dla twojego backendu, a nie dla przeglądarki: nie dopuszcza CORS, a klucz API nigdy nie powinien trafić na stronę internetową ani do aplikacji.

Podstawy

• Adres bazowy: https://reactive.chat/v1/
• Wersja: w ścieżce (v1). W ramach v1 pola mogą dochodzić, ale żadne nie znikają; ignoruj nieznane pola.
• Format: JSON, UTF-8. Czas jako ISO 8601 w UTC (2026-10-21T08:15:30.123Z). Identyfikatory są zwracane jako ciągi znaków ("id":"123").
• Nagłówki odpowiedzi: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
• Nieistniejąca ścieżka zwraca stronę 404 (nie JSON).

Klucze API

W koncie, w sekcji Klucze API (/app/api-keys, tylko właściciele i administratorzy). Nadajesz nazwę i zakres; klucz (rc_live_ + 48 znaków) jest pokazywany dokładnie raz, przechowujemy tylko jego hash.

Zakresy:

• tylko odczyt – read
• odczyt i zapis – read, write
• odczyt + dane odwiedzających – read, besucherdaten:lesen
• odczyt, zapis + dane odwiedzających – read, write, besucherdaten:lesen
• tylko import danych klientów – kundendaten:schreiben (Dane klientów)

Klucz należy do dokładnie jednej przestrzeni roboczej; żadna ścieżka ani parametr nie wybiera innej. Traci ważność, gdy go unieważnisz albo gdy osoba, która go utworzyła, nie jest już właścicielem ani administratorem przestrzeni roboczej. Daty wygaśnięcia nie ma – rotuj sam (utwórz nowy, przestaw, unieważnij stary).

Wysyłanie:

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

Równoważny jest nagłówek X-Api-Key: rc_live_... (odczytywany tylko wtedy, gdy nie ma Authorization: Bearer).

Limit zapytań

• 120 zapytań na minutę i klucz, stałe okno liczone od pełnej minuty. Liczy się każde zapytanie, także odrzucone.
• Każda odpowiedź zawiera X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset (sekundy do następnego okna, nie znacznik czasu).
• Powyżej limitu: 429 rate_limited z Retry-After.
• Po 60 nieudanych uwierzytelnieniach z jednego adresu w ciągu 15 minut: 429 z Retry-After: 900.

Format odpowiedzi

{ "data": { ... } }

Listy:

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

Paginacja: limit (domyślnie 25, najwyżej 100) i kursor – before_id przy listach „od najnowszych”, after_id przy listach „od najstarszych”. next pojawia się tylko wtedy, gdy has_more jest prawdą. Licznika całkowitego nie ma.

Treści żądań POST/PUT: tylko Content-Type: application/json (w przeciwnym razie 415), najwyżej 65 536 bajtów (w przeciwnym razie 413), obiekt JSON z najwyżej 32 poziomami zagnieżdżenia.

Format błędów

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

message to stałe angielskie zdanie dla programistów. Zależnie od błędu dochodzą param, required_scope, max, allowed, reason. Lista kodów jest zamknięta:

• 400 bad_request, bad_json
• 401 auth_required (brak klucza), auth_failed (nieprawidłowy lub unieważniony)
• 402 plan_required
• 403 insufficient_scope, workspace_inactive
• 404 not_found, conversation_not_found
• 405 method_not_allowed (z Allow)
• 409 conversation_closed, import_disabled
• 413 payload_too_large
• 415 unsupported_media_type
• 422 msg_too_long (z max)
• 429 rate_limited
• 500 internal, 501 not_implemented, 503 unavailable

Endpointy

Konto

• GET /v1/me – bez szczególnego zakresu. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Dobre do sprawdzenia klucza.

Projekty (read)

• GET /v1/projects – limit, before_id. Dla każdego projektu: id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
• GET /v1/projects/{id}

Rozmowy (read)

• GET /v1/conversations – od najnowszych. Filtry project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Dla każdej rozmowy: 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}

Wiadomości

• GET /v1/conversations/{id}/messages (read) – od najstarszych, after_id, limit. Dla każdej wiadomości: id, conversation_id, client_ulid, direction (in do odwiedzającego, out od odwiedzającego), author_type, author_id, kind, body, redacted, delivery_state, created_at; jeśli występują, card, cards, form, form_reply, action, quick_replies, quick_reply_of.
• GET /v1/messages (read) – wszystkie wiadomości przestrzeni roboczej jako strumień, conversation_id opcjonalnie, after_id, limit. Do pobierania bez webhooków.
• POST /v1/conversations/{id}/messages (write) – zapisanie wiadomości w rozmowie:

curl -X POST https://reactive.chat/v1/conversations/815/messages \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Twój zwrot do nas dotarł.","author_type":"agent","client_ulid":"01JAB3C4D5E6F7G8H9JKMNPQRS"}'

• body (String, obowiązkowe, najwyżej 4000 znaków)
• author_type (agent | bot | system, domyślnie agent) – nie w imieniu odwiedzającego
• client_ulid (ULID, opcjonalne) – dla idempotentności: ten sam identyfikator ponownie daje 200 z istniejącą wiadomością zamiast drugiej (201 za pierwszym razem).
• 409 conversation_closed przy zamkniętej rozmowie, 422 msg_too_long.
• Uwaga: tak zapisane wiadomości są przechowywane, ale do właśnie otwartego widżetu nie docierają od razu, tylko przy następnej synchronizacji. Do odpowiedzi na żywo użyj narzędzia MCP nachricht_senden (niżej).

Odwiedzający (read)

• GET /v1/visitors – lista odwiedzających na żywo: project_id, online (0/1), limit. Dla każdego odwiedzającego m.in. online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (z UTM), device, country, language, returning, conversation. Dodatkowo disabled_project_ids dla projektów, w których lista odwiedzających jest wyłączona.

Zdarzenia

• GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. Dla każdego zdarzenia id, project_id, source, type, session_id, conversation_id, payload, created_at.
• POST /v1/events (write) – dołączenie własnego zdarzenia z twojego systemu do sesji lub rozmowy:

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

type według ^[a-z][a-z0-9_.:-]{0,47}$, payload najwyżej 8192 bajty, ts w milisekundach (najwyżej 7 dni wstecz, najwyżej 5 minut naprzód). source to zawsze integration. Odpowiedź 201.

Reguły (read)

• GET /v1/rules – project_id. Dla każdego projektu source (custom albo default) i rules. Tylko do odczytu; reguły edytujesz w Dostosowaniu.

Hooki – zobacz Webhooki: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Dane klientów – zobacz Dane klientów: PUT i DELETE /v1/kundendaten/{user_id}.

Przykład: pobieranie otwartych rozmów

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

Serwer MCP

Dla narzędzi AI, które mówią Model Context Protocol, pod tym samym adresem bazowym działa serwer MCP:

• Adres: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, bezstanowy, bez batchingu). Dokładny adres pokazuje strona Klucze API.
• Uwierzytelnianie: ten sam klucz API jako Authorization: Bearer; ten sam limit zapytań.
• Wersje protokołu: 2026-07-28 (z server/discover; nagłówki MCP-Protocol-Version, Mcp-Method, a przy tools/call także Mcp-Name są obowiązkowe) oraz 2025-11-25, 2025-06-18 i 2025-03-26 (z initialize).
• Tylko z serwera: żądania z przeglądarkowym Origin są odrzucane kodem 403.

Narzędzia (tools/list pokazuje tylko te, do których uprawnia twój klucz):

• kb_suchen (read) – projekt, frage (najwyżej 500 znaków), n (1–10, domyślnie 5). Przeszukuje bazę wiedzy; najwyżej 20 wyszukiwań na minutę i klucz.
• gespraeche_auflisten (read) – projekt, status, seit (czas ISO), limit (najwyżej 100), vor_id.
• gespraech_lesen (read) – id, limit (najwyżej 200, domyślnie 100).
• nachricht_senden (write) – gespraech, text (najwyżej 4000 znaków), opcjonalnie als (e-mail agenta, który może odpowiadać w projekcie). Dostarcza od razu jako wiadomość agenta; asystent milknie w tej rozmowie.
• wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (najwyżej 60).

Bez besucherdaten:lesen imię, e-mail i telefon odwiedzających są skracane, a dane osobowe w tekstach maskowane. Błędy narzędzi przychodzą jako isError: true z identyfikatorami takimi jak project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Przykładowy wpis dla klienta MCP:

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

MCP i lista odwiedzających to nowe funkcje; mogą być wyłączone dla poszczególnych projektów (dany projekt zgłasza wtedy disabled).

Czego nie ma

• Osobistych tokenów agentów ani kluczy testowych; wszystkie klucze to klucze przestrzeni roboczej rc_live_.
• Endpointów do tworzenia rozmów, pisania w imieniu odwiedzających ani zmiany ustawień projektu, reguł czy bazy wiedzy.
• CORS – API nie jest przeznaczone dla przeglądarek.

Dalej: Webhooki · Integracje i kanały