API do servidor (REST v1) e MCP

A interface REST do reactive.chat para seu backend: chaves de API e escopos, limites de requisições, formatos de resposta e erro, paginação, todos os endpoints para projetos, conversas, mensagens, visitantes, eventos, regras e hooks, além do servidor MCP para ferramentas de IA.

A API do servidor é destinada ao seu backend, não ao navegador: ela não permite CORS, e uma chave de API nunca deve estar em uma página da web ou aplicativo.

Conceitos básicos

Base: https://reactive.chat/v1/
Versão: no caminho (v1). Na v1, novos campos são adicionados, mas nenhum é removido; ignore campos desconhecidos.
Formato: JSON, UTF-8. Horários em ISO 8601 e UTC (2026-10-21T08:15:30.123Z). Os IDs são retornados como strings ("id":"123").
Cabeçalhos de resposta: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
Um caminho inexistente retorna uma página 404 (não JSON).

Chaves de API

Na conta, em Chaves de API (/app/api-keys, somente proprietários e admins). Você define um nome e um escopo; a chave (rc_live_ + 48 caracteres) é exibida exatamente uma vez, e armazenamos apenas um hash.

Escopos:

somente leitura – read
leitura e escrita – read, write
leitura + dados de visitantes – read, besucherdaten:lesen
leitura, escrita + dados de visitantes – read, write, besucherdaten:lesen
só importação de dados de clientes – kundendaten:schreiben (Dados de clientes)

Uma chave pertence a exatamente um espaço de trabalho; nenhum caminho ou parâmetro seleciona outro. Ela deixa de ser válida quando você a revoga ou quando a pessoa que a criou deixa de ser proprietário ou admin do espaço de trabalho. Não há data de expiração: faça a rotação por conta própria (crie uma nova, passe a usá-la e revogue a antiga).

Envio:

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

O cabeçalho X-Api-Key: rc_live_... é equivalente (só é lido se não houver Authorization: Bearer).

Limite de requisições

120 requisições por minuto e por chave, em uma janela fixa alinhada ao início de cada minuto. Todas as requisições contam, inclusive as rejeitadas.
Todas as respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos até a próxima janela, não um timestamp).
Acima desse limite: 429 rate_limited com Retry-After.
Após 60 falhas de autenticação por endereço em 15 minutos: 429 com Retry-After: 900.

Formato de resposta

{ "data": { ... } }

Listas:

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

Paginação: limit (padrão 25, no máximo 100) e um cursor: before_id para listas com os itens mais recentes primeiro, after_id para listas com os mais antigos primeiro. next só aparece se has_more for verdadeiro. Não há contagem total.

Corpos de POST/PUT: somente Content-Type: application/json (caso contrário, 415), no máximo 65.536 bytes (caso contrário, 413), um objeto JSON com no máximo 32 níveis.

Formato de erro

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

message é uma frase fixa em inglês para desenvolvedores. Dependendo do erro, são acrescentados param, required_scope, max, allowed e reason. A lista de códigos é completa:

400 bad_request, bad_json
401 auth_required (sem chave), auth_failed (inválida ou revogada)
402 plan_required
403 insufficient_scope, workspace_inactive
404 not_found, conversation_not_found
405 method_not_allowed (com Allow)
409 conversation_closed, import_disabled
413 payload_too_large
415 unsupported_media_type
422 msg_too_long (com max)
429 rate_limited
500 internal, 501 not_implemented, 503 unavailable

Endpoints

Conta

GET /v1/me – não exige um escopo específico. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Útil para verificar uma chave.

Projetos (read)

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

Conversas (read)

GET /v1/conversations – mais recentes primeiro. Filtros project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Por conversa: 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}

Mensagens

GET /v1/conversations/{id}/messages (read) – mais antigas primeiro, after_id, limit. Por mensagem: id, conversation_id, client_ulid, direction (in para o visitante, out do visitante), author_type, author_id, kind, body, redacted, delivery_state, created_at; quando presentes, card, cards, form, form_reply, action, quick_replies, quick_reply_of.
GET /v1/messages (read) – todas as mensagens do espaço de trabalho como um fluxo, conversation_id opcional, after_id, limit. Para coletar mensagens sem webhooks.
POST /v1/conversations/{id}/messages (write) – escrever uma mensagem em uma conversa:

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 (string, obrigatório, no máximo 4.000 caracteres)
author_type (agent | bot | system, padrão agent) – não em nome do visitante
client_ulid (ULID, opcional) – para idempotência: usar o mesmo ID novamente retorna 200 com a mensagem existente em vez de criar outra (201 na primeira vez).
409 conversation_closed para uma conversa encerrada, 422 msg_too_long.
Observação: mensagens escritas dessa forma são armazenadas, mas não chegam imediatamente a um widget aberto naquele momento, apenas na próxima sincronização. Para respostas ao vivo, use a ferramenta MCP nachricht_senden (abaixo).

Visitantes (read)

GET /v1/visitors – lista de visitantes ao vivo: project_id, online (0/1), limit. Por visitante, entre outros: online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (com UTM), device, country, language, returning, conversation. Além disso, disabled_project_ids para projetos em que a lista de visitantes está desativada.

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) – associar um evento do seu sistema a uma sessão ou conversa:

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

type conforme ^[a-z][a-z0-9_.:-]{0,47}$, payload com no máximo 8.192 bytes, ts em milissegundos (no máximo 7 dias no passado e 5 minutos no futuro). source é sempre integration. Resposta 201.

Regras (read)

GET /v1/rules – project_id. Por projeto, source (custom ou default) e rules. Somente leitura; você edita as regras em Personalização.

Hooks – veja Webhooks: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Dados de clientes – veja Dados de clientes: PUT e DELETE /v1/kundendaten/{user_id}.

Exemplo: coletar conversas abertas

<?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 ferramentas de IA que usam o Model Context Protocol, há um servidor MCP sob a mesma base:

Endereço: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, sem estado, sem processamento em lote). O endereço exato aparece na página Chaves de API.
Autenticação: a mesma chave de API como Authorization: Bearer; o mesmo limite de requisições.
Versões do protocolo: 2026-07-28 (com server/discover; os cabeçalhos MCP-Protocol-Version, Mcp-Method e, para tools/call, Mcp-Name são obrigatórios), além de 2025-11-25, 2025-06-18 e 2025-03-26 (com initialize).
Somente no servidor: requisições com um Origin de navegador são rejeitadas com 403.

Ferramentas (tools/list mostra apenas as que sua chave pode usar):

kb_suchen (read) – projekt, frage (no máximo 500 caracteres), n (1–10, padrão 5). Pesquisa na base de conhecimento; no máximo 20 pesquisas por minuto e por chave.
gespraeche_auflisten (read) – projekt, status, seit (horário ISO), limit (no máximo 100), vor_id.
gespraech_lesen (read) – id, limit (no máximo 200, padrão 100).
nachricht_senden (write) – gespraech, text (no máximo 4.000 caracteres), opcionalmente als (e-mail de um atendente com permissão para responder no projeto). Entrega imediatamente como mensagem de atendente; o assistente deixa de responder nessa conversa.
wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (no máximo 60).

Sem besucherdaten:lesen, nome, e-mail e telefone dos visitantes são abreviados e os dados pessoais nos textos são ocultos. Os erros das ferramentas são retornados como isError: true, com identificadores como project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Exemplo de configuração para um cliente MCP:

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

O MCP e a lista de visitantes são recursos novos; podem estar desativados por projeto (o projeto afetado retorna disabled).

O que não existe

Não há tokens pessoais de atendentes nem chaves de teste; todas as chaves são chaves de espaço de trabalho rc_live_.
Não há endpoints para criar conversas, escrever em nome dos visitantes ou alterar configurações do projeto, regras ou a base de conhecimento.
Não há CORS: a API não é destinada a navegadores.

A seguir: Webhooks · Integrações e canais

آخر تحديث: 2026-10-25