前往首页

Sunucu API’si (REST v1) ve MCP

Arka ucunuz için reactive.chat REST arayüzü: API anahtarları ve kapsamlar, hız sınırı, yanıt ve hata biçimi, sayfalama, proje, sohbet, mesaj, ziyaretçi, olay, kural ve webhook uç noktaları; YZ araçları için MCP sunucusu.

Sunucu API’si arka ucunuz içindir; tarayıcı için değildir: CORS’a izin vermez; API anahtarı asla web sayfasına veya uygulamaya konmaz.

Temel bilgiler

Temel adres: https://reactive.chat/v1/
Sürüm: yolda (v1). v1 içinde alanlar eklenir, ancak hiçbiri kaldırılmaz; bilinmeyen alanları yok sayın.
Biçim: JSON, UTF-8. Zamanlar UTC olarak ISO 8601 biçiminde (2026-10-21T08:15:30.123Z). Kimlikler dize olarak döndürülür ("id":"123").
Yanıt başlıkları: Cache-Control: no-store, private, X-Content-Type-Options: nosniff.
Var olmayan yol 404 sayfası döndürür (JSON değil).

API anahtarları

Hesabınızda API anahtarları altında (/app/api-keys, yalnızca sahipler ve yöneticiler). Ad ve kapsam belirlersiniz; anahtar (rc_live_ + 48 karakter) yalnızca bir kez gösterilir ve yalnızca özetini saklarız.

Kapsamlar:

yalnızca okuma – read
okuma ve yazma – read, write
okuma + ziyaretçi verileri – read, besucherdaten:lesen
okuma, yazma + ziyaretçi verileri – read, write, besucherdaten:lesen
yalnızca müşteri verisi içe aktarma – kundendaten:schreiben (Müşteri verileri)

Anahtar tam olarak bir çalışma alanına aittir; hiçbir yol veya parametre başka bir çalışma alanı seçmez. İptal ettiğinizde veya oluşturan kişi artık çalışma alanının sahibi ya da yöneticisi olmadığında geçersiz olur. Son kullanma tarihi yoktur; kendiniz yenileyin (yenisini oluşturun, ona geçin, eskisini iptal edin).

Gönderim:

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

X-Api-Key: rc_live_... başlığı eşdeğerdir (yalnızca Authorization: Bearer yoksa okunur).

Hız sınırı

Dakika ve anahtar başına 120 istek; tam dakikaya hizalı sabit pencere. Reddedilenler dâhil her istek sayılır.
Her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset bulunur (sonraki pencereye kadar saniye; zaman damgası değil).
Aşılırsa: Retry-After ile 429 rate_limited.
Adres başına 15 dakika içinde 60 başarısız kimlik doğrulamasından sonra: Retry-After: 900 ile 429.

Yanıt biçimi

{ "data": { ... } }

Listeler:

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

Sayfalama: limit (varsayılan 25, en fazla 100) ve imleç: “en yeni önce” listelerinde before_id, “en eski önce” listelerinde after_id. next yalnızca has_more true ise bulunur. Toplam sayı yoktur.

POST/PUT gövdeleri: yalnızca Content-Type: application/json (aksi durumda 415), en fazla 65.536 bayt (aksi durumda 413), en fazla 32 düzeyli JSON nesnesi.

Hata biçimi

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

message, geliştiriciler için sabit İngilizce cümledir. Hataya bağlı olarak param, required_scope, max, allowed, reason eklenir. Kodların tam listesi:

400 bad_request, bad_json
401 auth_required (anahtar yok), auth_failed (geçersiz veya iptal edilmiş)
402 plan_required
403 insufficient_scope, workspace_inactive
404 not_found, conversation_not_found
405 method_not_allowed (Allow ile)
409 conversation_closed, import_disabled
413 payload_too_large
415 unsupported_media_type
422 msg_too_long (max ile)
429 rate_limited
500 internal, 501 not_implemented, 503 unavailable

Uç noktalar

Hesap

GET /v1/me – belirli bir kapsam gerektirmez. { key: {id, name, scopes}, workspace: {id, name}, rate_limit: {requests, window_seconds} }. Anahtarı kontrol etmek için uygundur.

Projeler (read)

GET /v1/projects – limit, before_id. Proje başına: id, name, domain, site_key, status, locale, created_at, updated_at, last_used_at.
GET /v1/projects/{id}

Sohbetler (read)

GET /v1/conversations – en yeni önce. Filtreler: project_id, status (open, bot, waiting, assigned, closed), limit, before_id. Sohbet başına: 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}

Mesajlar

GET /v1/conversations/{id}/messages (read) – en eski önce, after_id, limit. Mesaj başına: id, conversation_id, client_ulid, direction (ziyaretçiye doğru in, ziyaretçiden gelen out), author_type, author_id, kind, body, redacted, delivery_state, created_at; varsa card, cards, form, form_reply, action, quick_replies, quick_reply_of.
GET /v1/messages (read) – çalışma alanının tüm mesajları akış olarak; isteğe bağlı conversation_id, after_id, limit. Webhook olmadan toplamak için.
POST /v1/conversations/{id}/messages (write) – sohbete mesaj yazma:

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 (dize, zorunlu, en fazla 4.000 karakter)
author_type (agent | bot | system, varsayılan agent) – ziyaretçi adına yazılmaz
client_ulid (ULID, isteğe bağlı) – idempotans için: aynı kimlik tekrar gönderilirse ikinci mesaj yerine mevcut mesajla 200 döner (ilk seferde 201).
Kapalı sohbet için 409 conversation_closed, 422 msg_too_long.
Not: Bu şekilde yazılan mesajlar saklanır, ancak o anda açık widget’a hemen ulaşmaz; yalnızca sonraki eşitlemede ulaşır. Canlı yanıtlar için MCP aracı nachricht_senden kullanın (aşağıda).

Ziyaretçiler (read)

GET /v1/visitors – canlı ziyaretçi listesi: project_id, online (0/1), limit. Ziyaretçi başına diğerlerinin yanı sıra online, consent, first_seen_at, last_active_at, visitor_id, page, pages_viewed, source (UTM ile), device, country, language, returning, conversation. Ayrıca ziyaretçi listesinin kapalı olduğu projeler için disabled_project_ids.

Olaylar

GET /v1/events (read) – project_id, type, source (mp, rc, integration), after_id, limit. Olay başına id, project_id, source, type, session_id, conversation_id, payload, created_at.
POST /v1/events (write) – sisteminizden kendi olayınızı oturuma veya sohbete ekleme:

{ "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}$ ifadesiyle eşleşmelidir; payload en fazla 8.192 bayt; ts milisaniye cinsinden (en fazla 7 gün eski, en fazla 5 dakika ileride). source her zaman integration olur. Yanıt 201.

Kurallar (read)

GET /v1/rules – project_id. Proje başına source (custom veya default) ve rules. Salt okunur; kuralları Özelleştirme altında düzenlersiniz.

Webhook’lar – Webhook’lar bölümüne bakın: GET /v1/hooks, POST /v1/hooks, DELETE /v1/hooks/{id}.

Müşteri verileri – Müşteri verileri bölümüne bakın: PUT ve DELETE /v1/kundendaten/{user_id}.

Örnek: açık sohbetleri toplama

<?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 sunucusu

Model Context Protocol kullanan YZ araçları için aynı temel adres altında MCP sunucusu vardır:

Adres: POST https://reactive.chat/v1/mcp (Streamable HTTP, JSON-RPC 2.0, durumsuz, toplu istek yok). Tam adres API anahtarları sayfasında gösterilir.
Kimlik doğrulama: Authorization: Bearer olarak aynı API anahtarı; aynı hız sınırı.
Protokol sürümleri: 2026-07-28 (server/discover ile; MCP-Protocol-Version, Mcp-Method başlıkları ve tools/call için Mcp-Name zorunludur); ayrıca 2025-11-25, 2025-06-18 ve 2025-03-26 (initialize ile).
Yalnızca sunucu: Tarayıcı Origin başlığı içeren istekler 403 ile reddedilir.

Araçlar (tools/list yalnızca anahtarınızın kullanabildiklerini gösterir):

kb_suchen (read) – projekt, frage (en fazla 500 karakter), n (1–10, varsayılan 5). Bilgi tabanında arar; dakika ve anahtar başına en fazla 20 arama.
gespraeche_auflisten (read) – projekt, status, seit (ISO zamanı), limit (en fazla 100), vor_id.
gespraech_lesen (read) – id, limit (en fazla 200, varsayılan 100).
nachricht_senden (write) – gespraech, text (en fazla 4.000 karakter), isteğe bağlı als (projede yanıtlama yetkisi olan temsilcinin e-postası). Temsilci mesajı olarak hemen iletir; asistan bu sohbette sessiz kalır.
wissensluecken (read) – projekt, stand (offen, erledigt, ignoriert), limit (en fazla 60).

besucherdaten:lesen olmadan ziyaretçilerin adı, e-postası ve telefonu kısaltılır; metinlerdeki kişisel veriler maskelenir. Araç hataları isError: true ile ve project_not_found, conversation_not_found, conversation_closed, disabled, bad_argument, too_long, search_rate_limited gibi tanımlayıcılarla gelir.

MCP istemcisi için örnek kayıt:

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

MCP ve ziyaretçi listesi yeni özelliklerdir; proje başına kapatılabilirler (etkilenen proje disabled bildirir).

Bulunmayan özellikler

Kişisel temsilci token’ları ve test anahtarları yoktur; tüm anahtarlar rc_live_ çalışma alanı anahtarıdır.
Sohbet oluşturma, ziyaretçi adına yazma veya proje ayarlarını, kuralları ya da bilgi tabanını değiştirme uç noktaları yoktur.
CORS yoktur; API tarayıcılar için değildir.

Sonraki: Webhook’lar · Entegrasyonlar ve kanallar

最后更新: 2026-10-25