На главную

Серверный API (REST v1) и MCP

REST-интерфейс reactive.chat для бэкенда: API-ключи и права, ограничения частоты, форматы ответов и ошибок, пагинация, все конечные точки проектов, разговоров, сообщений, посетителей, событий, правил и хуков, а также MCP-сервер для ИИ-инструментов.

Серверный API предназначен для вашего бэкенда, а не браузера: CORS не разрешён, и API-ключу никогда не место на веб-странице или в приложении.

Основное

Базовый адрес: https://reactive.chat/v1/
Версия: в пути (v1). В пределах v1 поля добавляются, но не удаляются; игнорируйте неизвестные поля.
Формат: JSON, UTF-8. Время — ISO 8601 в UTC (2026-10-21T08:15:30.123Z). ID выводятся как строки ("id":"123").
Заголовки ответа: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
Несуществующий путь возвращает страницу 404 (не JSON).

API-ключи

В аккаунте, раздел API-ключи (/app/api-keys, только владельцы и администраторы). Вы задаёте имя и область прав; ключ (rc_live_ + 48 символов) показывается ровно один раз, а мы храним только хеш.

Области прав:

Только чтение — read
Чтение и запись — read, write
Чтение + данные посетителей — read, besucherdaten:lesen
Чтение, запись + данные посетителей — read, write, besucherdaten:lesen
Только импорт данных клиентов — kundendaten:schreiben (Данные клиентов)

Ключ относится ровно к одному рабочему пространству; ни путь, ни параметр не выбирают другое. Он становится недействительным при отзыве или когда создавший его человек больше не владелец или администратор пространства. Срока истечения нет; выполняйте ротацию самостоятельно (создайте новый, переключитесь на него, отзовите старый).

Отправка:

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

Заголовок X-Api-Key: rc_live_... равнозначен (читается только при отсутствии Authorization: Bearer).

Ограничение частоты

120 запросов в минуту на ключ, фиксированное окно с началом в целую минуту. Каждый запрос учитывается, включая отклонённый.
В каждом ответе есть X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (секунды до следующего окна, а не отметка времени).
При превышении: 429 rate_limited с Retry-After.
После 60 неудачных аутентификаций с одного адреса за 15 минут: 429 с Retry-After: 900.

Формат ответа

{ "data": { ... } }

Списки:

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

Пагинация: limit (по умолчанию 25, максимум 100) и курсор: before_id для списков от новых к старым, after_id для списков от старых к новым. next присутствует, только если has_more равно true. Общего количества нет.

Тела POST/PUT: только Content-Type: application/json (иначе 415), не более 65 536 байт (иначе 413), JSON-объект с вложенностью до 32 уровней.

Формат ошибки

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

message — фиксированное английское предложение для разработчиков. В зависимости от ошибки добавляются param, required_scope, max, allowed, reason. Полный список кодов:

400 bad_request, bad_json
401 auth_required (нет ключа), auth_failed (неверный или отозван)
402 plan_required
403 insufficient_scope, workspace_inactive
404 not_found, conversation_not_found
405 method_not_allowed (с Allow)
409 conversation_closed, import_disabled
413 payload_too_large
415 unsupported_media_type
422 msg_too_long (с max)
429 rate_limited
500 internal, 501 not_implemented, 503 unavailable

Конечные точки

Аккаунт

GET /v1/me — особые права не нужны. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Подходит для проверки ключа.

Проекты (read)

GET /v1/projects — limit, before_id. Для каждого проекта: id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
GET /v1/projects/{id}

Разговоры (read)

GET /v1/conversations — от новых к старым. Фильтры project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Для каждого разговора: 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}

Сообщения

GET /v1/conversations/{id}/messages (read) — от старых к новым, after_id, limit. Для каждого сообщения: id, conversation_id, client_ulid, direction (in к посетителю, out от посетителя), author_type, author_id, kind, body, redacted, delivery_state, created_at; при наличии card, cards, form, form_reply, action, quick_replies, quick_reply_of.
GET /v1/messages (read) — все сообщения рабочего пространства потоком, необязательный conversation_id, after_id, limit. Для сбора без вебхуков.
POST /v1/conversations/{id}/messages (write) — запись сообщения в разговор:

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 (строка, обязательно, не более 4000 символов)
author_type (agent | bot | system, по умолчанию agent) — не от имени посетителя
client_ulid (ULID, необязательно) — для идемпотентности: повторный запрос с тем же ID возвращает 200 с имеющимся сообщением вместо создания второго (при первом запросе 201).
409 conversation_closed для закрытого разговора, 422 msg_too_long.
Примечание: записанные таким способом сообщения сохраняются, но не поступают немедленно в сейчас открытый виджет — только при следующей синхронизации. Для ответов в реальном времени используйте MCP-инструмент nachricht_senden (ниже).

Посетители (read)

GET /v1/visitors — список посетителей в реальном времени: project_id, online (0/1), limit. Для каждого посетителя, среди прочего, online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (с UTM), device, country, language, returning, conversation. Дополнительно disabled_project_ids для проектов, в которых список посетителей отключён.

События

GET /v1/events (read) — project_id, type, source (mp, rc, integration), after_id, limit. Для каждого события id, project_id, source, type, session_id, conversation_id, payload, created_at.
POST /v1/events (write) — добавление собственного события из вашей системы к сеансу или разговору:

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

type соответствует ^[a-z][a-z0-9_.:-]{0,47}$, payload не более 8192 байт, ts в миллисекундах (не старше 7 дней и не более чем на 5 минут в будущем). source всегда integration. Ответ 201.

Правила (read)

GET /v1/rules — project_id. Для каждого проекта source (custom или default) и rules. Только чтение; правила редактируются в разделе Настройка.

Хуки — см. Вебхуки: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Данные клиентов — см. Данные клиентов: PUT и DELETE /v1/kundendaten/{user_id}.

Пример: сбор открытых разговоров

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

MCP-сервер

Для ИИ-инструментов, поддерживающих Model Context Protocol, под тем же базовым адресом есть MCP-сервер:

Адрес: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, без состояния и пакетных запросов). Точный адрес показан на странице API-ключи.
Аутентификация: тот же API-ключ как Authorization: Bearer; тот же лимит частоты.
Версии протокола: 2026-07-28 (с server/discover; обязательны заголовки MCP-Protocol-Version, Mcp-Method и для tools/call — Mcp-Name), а также 2025-11-25, 2025-06-18 и 2025-03-26 (с initialize).
Только сервер: запросы с браузерным Origin отклоняются с 403.

Инструменты (tools/list показывает лишь разрешённые вашему ключу):

kb_suchen (read) — projekt, frage (не более 500 символов), n (1–10, по умолчанию 5). Поиск в базе знаний; не более 20 поисков в минуту на ключ.
gespraeche_auflisten (read) — projekt, status, seit (время ISO), limit (не более 100), vor_id.
gespraech_lesen (read) — id, limit (не более 200, по умолчанию 100).
nachricht_senden (write) — gespraech, text (не более 4000 символов), необязательный als (электронная почта оператора с правом ответа в проекте). Доставляет немедленно как сообщение оператора; ассистент замолкает в этом разговоре.
wissensluecken (read) — projekt, stand (offen, erledigt, ignoriert), limit (не более 60).

Без besucherdaten:lesen имя, электронная почта и телефон посетителей сокращаются, а персональные данные в текстах скрываются. Ошибки инструментов поступают как isError: true с идентификаторами вроде project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited.

Пример записи для MCP-клиента:

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

MCP и список посетителей — новые функции; их можно отключить для отдельного проекта (тогда затронутый проект сообщает disabled).

Чего нет

Нет личных токенов операторов и тестовых ключей; все ключи — ключи рабочего пространства rc_live_.
Нет конечных точек для создания разговоров, записи от имени посетителей или изменения настроек проекта, правил и базы знаний.
Нет CORS — API не предназначен для браузеров.

Далее: Вебхуки · Интеграции и каналы

Обновлено: 2026-10-25