홈으로

서버 API(REST v1)와 MCP

백엔드용 reactive.chat REST 인터페이스: API 키와 권한 범위, 빈도 제한, 응답·오류 형식, 페이지 나누기, 프로젝트·대화·메시지·방문자·이벤트·규칙·훅의 모든 엔드포인트와 AI 도구용 MCP 서버.

서버 API는 브라우저가 아닌 백엔드용입니다. CORS를 허용하지 않으며 API 키를 웹페이지나 앱에 넣어서는 안 됩니다.

기본 사항

기본 주소: https://reactive.chat/v1/
버전: 경로에 포함됩니다(v1). v1에서는 필드를 추가하지만 제거하지 않습니다. 알 수 없는 필드는 무시합니다.
형식: JSON, UTF-8입니다. 시각은 UTC의 ISO 8601(2026-10-21T08:15:30.123Z)이며 ID는 문자열("id":"123")로 출력됩니다.
응답 헤더: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
존재하지 않는 경로는 JSON이 아닌 404 페이지를 반환합니다.

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이 포함됩니다. 마지막 값은 타임스탬프가 아닌 다음 구간까지의 초입니다.
초과하면 Retry-After와 함께 429 rate_limited를 반환합니다.
주소별로 15분 안에 인증이 60회 실패하면 Retry-After: 900과 함께 429를 반환합니다.

응답 형식

{ "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입니다. 깊이 최대 32단계의 JSON 객체여야 합니다.

오류 형식

{ "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을 지원하는 AI 도구용 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