API de servidor (REST v1) y MCP

La API de servidor está pensada para su backend, no para el navegador: no permite CORS y una clave de API nunca debe incluirse en una página web o aplicación.

Fundamentos

• Base: https://reactive.chat/v1/
• Versión: en la ruta (v1). Dentro de v1 se añaden campos, pero no se elimina ninguno; ignore los campos desconocidos.
• Formato: JSON, UTF-8. Fechas y horas en ISO 8601 y UTC (2026-10-21T08:15:30.123Z). Los ID se devuelven como cadenas ("id":"123").
• Cabeceras de respuesta: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
• Una ruta inexistente devuelve una página 404 (no JSON).

Claves de API

En su cuenta, en Claves de API (/app/api-keys, solo propietarios y administradores). Asigne un nombre y un alcance; la clave (rc_live_ + 48 caracteres) se muestra exactamente una vez y solo guardamos un hash.

Alcances:

• solo lectura – read
• lectura y escritura – read, write
• lectura + datos de visitantes – read, besucherdaten:lesen
• lectura, escritura + datos de visitantes – read, write, besucherdaten:lesen
• solo importación de datos de clientes – kundendaten:schreiben (Datos de clientes)

Una clave pertenece exactamente a un espacio de trabajo; ninguna ruta ni parámetro permite seleccionar otro. Queda invalidada al revocarla o cuando quien la creó deja de ser propietario o administrador del espacio de trabajo. No tiene fecha de caducidad; realice usted la rotación (crear una nueva, cambiar a ella y revocar la anterior).

Envío:

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

La cabecera X-Api-Key: rc_live_... es equivalente (solo se lee si no hay Authorization: Bearer).

Limitación de solicitudes

• 120 solicitudes por minuto y clave, en una ventana fija alineada con el inicio de cada minuto. Todas las solicitudes cuentan, incluidas las rechazadas.
• Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta la siguiente ventana, no una marca de tiempo).
• Si se supera el límite: 429 rate_limited con Retry-After.
• Tras 60 autenticaciones fallidas por dirección en 15 minutos: 429 con Retry-After: 900.

Formato de respuesta

{ "data": { ... } }

Listas:

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

Paginación: limit (predeterminado 25, máximo 100) y un cursor: before_id para listas con los elementos más recientes primero, after_id para las que muestran primero los más antiguos. next solo aparece si has_more es verdadero. No hay un recuento total.

Cuerpos de POST/PUT: solo Content-Type: application/json (de lo contrario, 415), hasta 65 536 bytes (de lo contrario, 413), un objeto JSON con un máximo de 32 niveles.

Formato de error

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

message es una frase fija en inglés para desarrolladores. Según el error, se añaden param, required_scope, max, allowed y reason. La lista de códigos es exhaustiva:

• 400 bad_request, bad_json
• 401 auth_required (sin clave), auth_failed (no válida o revocada)
• 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

Endpoints

Cuenta

• GET /v1/me – no requiere un alcance específico. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Útil para comprobar una clave.

Proyectos (read)

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

Conversaciones (read)

• GET /v1/conversations – las más recientes primero. Filtros project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Por conversación: 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}

Mensajes

• GET /v1/conversations/{id}/messages (read) – los más antiguos primero, after_id, limit. Por mensaje: id, conversation_id, client_ulid, direction (in hacia el visitante, out desde el visitante), author_type, author_id, kind, body, redacted, delivery_state, created_at; cuando existan, card, cards, form, form_reply, action, quick_replies, quick_reply_of.
• GET /v1/messages (read) – todos los mensajes del espacio de trabajo como flujo, conversation_id opcional, after_id, limit. Para obtenerlos sin webhooks.
• POST /v1/conversations/{id}/messages (write) – escribir un mensaje en una conversación:

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 (cadena, obligatorio, hasta 4000 caracteres)
• author_type (agent | bot | system, predeterminado agent) – no en nombre del visitante
• client_ulid (ULID, opcional) – para la idempotencia: repetir el mismo ID devuelve 200 con el mensaje existente en lugar de uno nuevo (201 la primera vez).
• 409 conversation_closed para una conversación cerrada, 422 msg_too_long.
• Nota: los mensajes escritos así se guardan, pero no llegan de inmediato a un widget que esté abierto en ese momento, sino en la siguiente sincronización. Para respuestas en vivo, utilice la herramienta MCP nachricht_senden (más abajo).

Visitantes (read)

• GET /v1/visitors – lista de visitantes en vivo: project_id, online (0/1), limit. Por visitante, entre otros, online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (con UTM), device, country, language, returning, conversation. Además, disabled_project_ids para los proyectos en los que la lista de visitantes está desactivada.

Eventos

• GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. Por evento: id, project_id, source, type, session_id, conversation_id, payload, created_at.
• POST /v1/events (write) – vincular un evento propio de su sistema a una sesión o conversación:

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

type debe cumplir ^[a-z][a-z0-9_.:-]{0,47}$, payload admite hasta 8192 bytes, ts se indica en milisegundos (como máximo 7 días de antigüedad y 5 minutos en el futuro). source siempre es integration. Respuesta 201.

Reglas (read)

• GET /v1/rules – project_id. Por proyecto: source (custom o default) y rules. Solo lectura; las reglas se editan en Personalización.

Hooks – véase Webhooks: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Datos de clientes – véase Datos de clientes: PUT y DELETE /v1/kundendaten/{user_id}.

Ejemplo: obtener conversaciones abiertas

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

Servidor MCP

Para herramientas de IA compatibles con el Model Context Protocol, hay un servidor MCP bajo la misma base:

• Dirección: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, sin estado ni procesamiento por lotes). La dirección exacta aparece en la página Claves de API.
• Autenticación: la misma clave de API como Authorization: Bearer; el mismo límite de solicitudes.
• Versiones del protocolo: 2026-07-28 (con server/discover; son obligatorias las cabeceras MCP-Protocol-Version, Mcp-Method y, para tools/call, Mcp-Name), además de 2025-11-25, 2025-06-18 y 2025-03-26 (con initialize).
• Solo desde el servidor: las solicitudes con Origin de navegador se rechazan con 403.

Herramientas (tools/list solo muestra las que permite su clave):

• kb_suchen (read) – projekt, frage (hasta 500 caracteres), n (1–10, predeterminado 5). Busca en la base de conocimiento; hasta 20 búsquedas por minuto y clave.
• gespraeche_auflisten (read) – projekt, status, seit (hora ISO), limit (máximo 100), vor_id.
• gespraech_lesen (read) – id, limit (máximo 200, predeterminado 100).
• nachricht_senden (write) – gespraech, text (hasta 4000 caracteres), opcionalmente als (correo de un agente con permiso para responder en el proyecto). Entrega el mensaje de inmediato como mensaje de agente; el asistente deja de responder en esa conversación.
• wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (máximo 60).

Sin besucherdaten:lesen, el nombre, correo y teléfono de los visitantes se muestran abreviados y los datos personales de los textos se ocultan. Los errores de herramientas se devuelven como isError: true con identificadores como project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Entrada de ejemplo para un cliente MCP:

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

MCP y la lista de visitantes son funciones nuevas; pueden estar desactivadas por proyecto (el proyecto afectado devuelve entonces disabled).

Qué no existe

• No hay tokens personales de agente ni claves de prueba; todas las claves son claves de espacio de trabajo rc_live_.
• No hay endpoints para crear conversaciones, escribir en nombre de visitantes ni cambiar ajustes de proyectos, reglas o la base de conocimiento.
• Sin CORS: la API no está pensada para navegadores.

Siguiente: Webhooks · Integraciones y canales