トップページへ

サーバーAPI（REST v1）とMCP

バックエンド向けreactive.chat RESTインターフェース：APIキーと権限範囲、頻度制限、応答とエラー形式、ページ分割、プロジェクト・会話・メッセージ・訪問者・イベント・ルール・フックの各エンドポイント、AIツール向けMCPサーバー。

サーバーAPIは、ブラウザーではなく運営側のバックエンド向けです。CORSを許可せず、APIキーをWebページやアプリに含めてはいけません。

基本

ベース： 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文字）が表示されるのは1回だけで、当社はハッシュだけを保存します。

権限範囲：

読み取り専用 – read
読み取りと書き込み – read、write
読み取り＋訪問者データ – read、besucherdaten:lesen
読み取り、書き込み＋訪問者データ – read、write、besucherdaten:lesen
顧客データのインポートのみ – kundendaten:schreiben（顧客データ）

キーは必ず1つのワークスペースに属し、別のワークスペースをパスやパラメーターで選ぶことはできません。キーを失効させたとき、または作成者がワークスペースの所有者や管理者ではなくなったときに無効になります。有効期限はありません。自分でローテーションしてください（新規作成、切り替え、古いキーの失効）。

送信方法：

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

X-Api-Key: rc_live_...ヘッダーも同等です。ただし、Authorization: Bearerがない場合にのみ読み取ります。

頻度制限

キーごとに毎分120リクエスト。毎分00秒にそろえた固定の時間枠です。拒否されたものを含む、すべてのリクエストを数えます。
すべての応答にX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetを付けます。Resetは次の時間枠までの秒数で、タイムスタンプではありません。
超過時は、Retry-After付きの429 rate_limitedを返します。
1アドレスで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を指定できます。Webhookを使わずに収集する用途です。
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（文字列、必須、最大4,000文字）
author_type（agent | bot | system、既定はagent） – 訪問者の代理ではありません。
client_ulid（ULID、任意） – 冪等性のために使います。同じIDを再送すると、2件目を作らず、既存のメッセージを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は最大8,192バイト、tsはミリ秒（最大7日前、未来は最大5分先）です。sourceは常にintegrationです。応答は201です。

ルール（read）

GET /v1/rules – project_id。各プロジェクトにsource（customまたはdefault）とrulesがあります。読み取り専用です。ルールはカスタマイズで編集します。

フック – Webhookを参照：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（最大4,000文字）、任意の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はブラウザー向けではありません。

次：Webhook · 連携とチャネル

最終更新: 2026-10-25