API server (REST v1) e MCP

L’API server è destinata al Suo backend, non al browser: non consente CORS e una chiave API non deve mai trovarsi in una pagina web o in un’app.

Nozioni di base

• Base: https://reactive.chat/v1/
• Versione: nel percorso (v1). All’interno di v1 vengono aggiunti campi, ma non ne vengono rimossi; ignori quelli sconosciuti.
• Formato: JSON, UTF-8. Orari ISO 8601 in UTC (2026-10-21T08:15:30.123Z). Gli ID vengono restituiti come stringhe ("id":"123").
• Intestazioni di risposta: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
• Un percorso inesistente restituisce una pagina 404 (non JSON).

Chiavi API

Nell’account, in Chiavi API (/app/api-keys, solo proprietari e amministratori). Assegna un nome e un ambito; la chiave (rc_live_ + 48 caratteri) viene mostrata una sola volta e ne conserviamo solo un hash.

Ambiti:

• sola lettura: read
• lettura e scrittura: read, write
• lettura + dati dei visitatori: read, besucherdaten:lesen
• lettura, scrittura + dati dei visitatori: read, write, besucherdaten:lesen
• solo importazione dati dei clienti: kundendaten:schreiben (Dati dei clienti)

Una chiave appartiene esattamente a uno spazio di lavoro; nessun percorso o parametro ne seleziona un altro. Diventa non valida quando la revoca o quando chi l’ha creata non è più proprietario o amministratore dello spazio. Non ha scadenza: esegua personalmente la rotazione (ne crei una nuova, la sostituisca e revochi la precedente).

Invio:

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

L’intestazione X-Api-Key: rc_live_... è equivalente (viene letta solo in assenza di Authorization: Bearer).

Limitazione delle richieste

• 120 richieste al minuto per chiave, finestra fissa allineata al minuto intero. Ogni richiesta conta, anche se rifiutata.
• Ogni risposta contiene X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi fino alla finestra successiva, non un timestamp).
• Oltre il limite: 429 rate_limited con Retry-After.
• Dopo 60 autenticazioni fallite per indirizzo in 15 minuti: 429 con Retry-After: 900.

Formato delle risposte

{ "data": { ... } }

Elenchi:

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

Paginazione: limit (predefinito 25, massimo 100) e un cursore: before_id per gli elenchi dal più recente, after_id per quelli dal meno recente. next è presente solo se has_more è true. Non esiste un conteggio totale.

Corpi di POST/PUT: solo Content-Type: application/json (altrimenti 415), massimo 65.536 byte (altrimenti 413), un oggetto JSON con massimo 32 livelli.

Formato degli errori

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

message è una frase inglese fissa per sviluppatori. A seconda dell’errore vengono aggiunti param, required_scope, max, allowed e reason. L’elenco dei codici è completo:

• 400 bad_request, bad_json
• 401 auth_required (nessuna chiave), auth_failed (non valida o revocata)
• 402 plan_required
• 403 insufficient_scope, workspace_inactive
• 404 not_found, conversation_not_found
• 405 method_not_allowed (con Allow)
• 409 conversation_closed, import_disabled
• 413 payload_too_large
• 415 unsupported_media_type
• 422 msg_too_long (con max)
• 429 rate_limited
• 500 internal, 501 not_implemented, 503 unavailable

Endpoint

Account

• GET /v1/me: nessun ambito specifico richiesto. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Utile per verificare una chiave.

Progetti (read)

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

Conversazioni (read)

• GET /v1/conversations: prima le più recenti. Filtri project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Per conversazione: 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}

Messaggi

• GET /v1/conversations/{id}/messages (read): prima i meno recenti, after_id, limit. Per messaggio: id, conversation_id, client_ulid, direction (in verso il visitatore, out dal visitatore), author_type, author_id, kind, body, redacted, delivery_state, created_at; se presenti card, cards, form, form_reply, action, quick_replies, quick_reply_of.
• GET /v1/messages (read): tutti i messaggi dello spazio di lavoro come flusso, conversation_id facoltativo, after_id, limit. Per la raccolta senza webhook.
• POST /v1/conversations/{id}/messages (write): scrivere un messaggio in una conversazione:

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 (stringa, obbligatorio, massimo 4000 caratteri)
• author_type (agent | bot | system, predefinito agent): non in nome del visitatore
• client_ulid (ULID, facoltativo): per l’idempotenza; ripetere lo stesso ID restituisce 200 con il messaggio esistente anziché crearne un secondo (201 la prima volta).
• 409 conversation_closed per una conversazione chiusa, 422 msg_too_long.
• Nota: i messaggi scritti così vengono memorizzati, ma non raggiungono subito un widget attualmente aperto, solo alla sincronizzazione successiva. Per risposte in tempo reale usi lo strumento MCP nachricht_senden (sotto).

Visitatori (read)

• GET /v1/visitors: elenco visitatori in tempo reale: project_id, online (0/1), limit. Per visitatore, tra gli altri: online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (con UTM), device, country, language, returning, conversation. Inoltre disabled_project_ids per i progetti in cui l’elenco visitatori è disattivato.

Eventi

• GET /v1/events (read): project_id, type, source (mp, rc, integration), after_id, limit. Per evento: id, project_id, source, type, session_id, conversation_id, payload, created_at.
• POST /v1/events (write): associare un evento del Suo sistema a una sessione o conversazione:

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

type conforme a ^[a-z][a-z0-9_.:-]{0,47}$, payload di massimo 8192 byte, ts in millisecondi (non più vecchio di 7 giorni, non più avanti di 5 minuti). source è sempre integration. Risposta 201.

Regole (read)

• GET /v1/rules: project_id. Per progetto source (custom o default) e rules. Sola lettura; modifica le regole in Personalizzazione.

Hook: vedere Webhook: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Dati dei clienti: vedere Dati dei clienti: PUT e DELETE /v1/kundendaten/{user_id}.

Esempio: raccogliere le conversazioni aperte

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

Per gli strumenti IA che supportano il Model Context Protocol esiste un server MCP sotto la stessa base:

• Indirizzo: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, senza stato, senza elaborazione in batch). L’indirizzo esatto è mostrato nella pagina Chiavi API.
• Autenticazione: la stessa chiave API come Authorization: Bearer; lo stesso limite di richieste.
• Versioni del protocollo: 2026-07-28 (con server/discover; sono richieste le intestazioni MCP-Protocol-Version, Mcp-Method e, per tools/call, Mcp-Name), oltre a 2025-11-25, 2025-06-18 e 2025-03-26 (con initialize).
• Solo server: le richieste con un Origin del browser vengono rifiutate con 403.

Strumenti (tools/list mostra solo quelli consentiti alla chiave):

• kb_suchen (read): projekt, frage (massimo 500 caratteri), n (1–10, predefinito 5). Cerca nella knowledge base; massimo 20 ricerche al minuto per chiave.
• gespraeche_auflisten (read): projekt, status, seit (ora ISO), limit (massimo 100), vor_id.
• gespraech_lesen (read): id, limit (massimo 200, predefinito 100).
• nachricht_senden (write): gespraech, text (massimo 4000 caratteri), facoltativamente als (e-mail di un operatore autorizzato a rispondere nel progetto). Consegna immediatamente come messaggio dell’operatore; l’assistente smette di rispondere in questa conversazione.
• wissensluecken (read): projekt, stand (offen, erledigt, ignoriert), limit (massimo 60).

Senza besucherdaten:lesen, nome, e-mail e telefono dei visitatori vengono abbreviati e i dati personali nei testi mascherati. Gli errori degli strumenti arrivano come isError: true con identificatori come project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Voce di esempio per un client MCP:

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

MCP e l’elenco visitatori sono funzioni nuove; possono essere disattivate per progetto (il progetto interessato segnala allora disabled).

Che cosa non esiste

• Nessun token personale per operatori e nessuna chiave di test; tutte sono chiavi di spazio di lavoro rc_live_.
• Nessun endpoint per creare conversazioni, scrivere in nome dei visitatori o modificare impostazioni del progetto, regole o knowledge base.
• Nessun CORS: l’API non è destinata ai browser.

Successivo: Webhook · Integrazioni e canali