Chatbot REST API-Referenz

REST API

Senden Sie eine Nachricht an Ihren Chatbot und erhalten Sie eine KI-generierte Antwort über einfaches HTTP. Nutzen Sie dies, um eine eigene Chat-UI, eine mobile App oder eine Backend-Automatisierung zu erstellen. Jeder Endpunkt wird über denselben Ursprung wie Ihr Widget-Skript bereitgestellt (https://webchatagent.com).

Verwenden Sie JavaScript oder TypeScript? Das JavaScript SDK (npm install webchatagent) kapselt diese Endpunkte mit typisierten Funktionen, Streaming und Live-Chat.

Wie eine Unterhaltung funktioniert

  1. Senden Sie die message des Benutzers und Ihre chatbotId per POST an /api/chat.
  2. Lesen Sie die reply aus dem JSON-Body. Lesen Sie den Response-Header X-Chat-Session-Id, das ist Ihre Sitzungs-ID.
  3. Senden Sie für die nächste Nachricht dieselbe Sitzungs-ID im Request-Header X-Chat-Session-Id. Der Server verfügt nun über den Kontext der Unterhaltung: Nachrichtenverlauf, quellenbasierten Wissenskontext (Retrieval-Augmented Generation, RAG) und den Status des Live-Chats.
  4. Wiederholen Sie diesen Vorgang. Lassen Sie den Header weg, wenn Sie eine neue Unterhaltung beginnen möchten.

Der Server verfolgt den Verlauf pro Sitzung, sodass Sie immer nur die neueste Nachricht senden, nie das vollständige Transkript.

Authentifizierung

Die API verwendet eine domainbasierte Authentifizierung: Es gibt keinen API-Schlüssel. Jede Anfrage wird anhand der für den Chatbot konfigurierten Erlaubten Domains über den Origin/Referer der Anfrage geprüft. Eine Anfrage von einer nicht erlaubten Domain erhält den Statuscode 403.

Senden Sie bei KI Team Wiki Chatbots mit geschütztem Zugang zusätzlich den Header X-Wiki-Auth mit dem Authentifizierungs-Token des Wikis (der Wert lautet wiki_auth_<subdomain>). Ohne diesen Header geben geschützte Wikis den Statuscode 403 zurück.

Eine Nachricht senden

POST https://webchatagent.com/api/chat

Headers

HeaderRequiredDescription
Content-TypeJaMuss application/json sein.
X-Chat-Session-IdNeinSitzungs-ID (eine UUID) für die Fortführung der Unterhaltung. Bei der ersten Anfrage weglassen; der Response-Header gibt eine neue zurück. Sie können auch selbst eine zufällige UUID erstellen. Jeder Wert, der keine UUID ist, wird durch eine neue Sitzung ersetzt.
AcceptNeintext/event-stream, um die Antwort als Stream zu empfangen (siehe Streaming).
Accept-LanguageNeinBevorzugte Sprache für die Antwort, z. B. de.

Request Body

FeldTypeRequiredDescription
messagestringJaDie Nachricht des Benutzers. Maximal 700 Zeichen. Darf nicht leer sein.
chatbotIdstring (UUID)JaDie ID Ihres Chatbots aus den Einstellungen des Chatbots.
pageUrlstringNeinDie vollständige Seiten-URL, auf der sich der Besucher befindet (window.location.href). Wird für seitenbezogenes Abrufen verwendet; wird anhand Ihrer erlaubten Domains validiert.
contextDataobjectNeinFlacher Schlüssel-Wert-Kontext über die Sitzung des Besuchers (max. 20 Schlüssel, 64 Zeichen pro Schlüssel, 500 Zeichen für String-, Zahlen- oder Boolean-Werte). Wird nur für diese Anfrage in den KI-Prompt eingefügt, nie als eigener Datensatz gespeichert; die KI behandelt Werte als Daten, nicht als Anweisungen, und kann sie in Argumenten für Tools und API-Connectors verwenden. Siehe Sitzungskontext-Daten.

Beispielanfrage

{
  "message": "What are your business hours?",
  "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Antwort

Die Sitzungs-ID wird im Response-Header X-Chat-Session-Id zurückgegeben, nicht im Body.

FeldTypeDescription
replystringDie Antwort als Markdown. Sie kann mit einem ausgeblendeten HTML-Kommentar <!-- SUGGESTED_BUTTONS: [{"label": "...", "text": "..."}] --> enden, der vorgeschlagene Folgefragen enthält: Zeigen Sie label auf einer Schaltfläche an, senden Sie beim Klicken text und entfernen Sie den Kommentar vor dem Rendern.
sourcesarrayQuellen, auf denen die Antwort basiert (siehe unten). Leer, falls keine verwendet wurden.
modestringModus der Unterhaltung: bot (KI antwortet) oder human (ein menschlicher Mitarbeiter hat übernommen). Vorhanden, wenn relevant.
statusstringLive-Chat-Status: waiting, open oder closed. Nur vorhanden, wenn Live-Chat für die Sitzung aktiv ist.
aiGeneratedbooleantrue, wenn die KI die Antwort verfasst hat. Fehlt, während ein menschlicher Mitarbeiter die Unterhaltung führt.
conversationTooLongbooleanDie Unterhaltung hat ihr Längenlimit erreicht. Starten Sie eine neue Sitzung.

Wenn ein menschlicher Mitarbeiter übernommen hat (mode: "human", status: "open"), kann die reply leer sein, da der Mitarbeiter separat antwortet. Während eine Übernahme auf waiting steht, ist die Antwort ein kurzer Hinweis wie "Ein Teammitglied wird in Kürze beitreten."

Sources-Array

Jedes Quellenobjekt:

FeldTypeDescription
typestringweb (eine Webseite), product (strukturierte Produktdaten) oder fileSource (ein Dokument aus einem verbundenen Dateispeicher).
sourcestringFür web: die Seiten-URL. Für product: die Produktkennung. Für fileSource: die Dokument-ID.
dataobjectNur für product. Enthält id, dataType, format, data und sourceUrl.

Beispielantwort

{
  "reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
  "sources": [
    {
      "type": "web",
      "source": "https://example.com/contact"
    }
  ],
  "mode": "bot"
}

Streaming

Senden Sie Accept: text/event-stream, um die Antwort zu empfangen, während sie generiert wird. Wenn für den Chatbot Streaming aktiviert ist, ist die Antwort ein Stream von Server-Sent Events, jeweils eine einzelne data:-Zeile mit einem JSON-Objekt, getrennt durch eine Leerzeile:

data: {"type":"token","data":"Our business hours "}

data: {"type":"token","data":"are Monday to Friday."}

data: {"type":"done","reply":"Our business hours are Monday to Friday.","sources":[],"conversationTooLong":false,"aiGenerated":true}
typeFelderBedeutung
tokendataNächster Teil der Antwort. Hängen Sie ihn an. Der Text kann unvollständiges Markdown und den Anfang des Vorschlagskommentars enthalten.
tool_callnameDer Bot verwendet ein Tool, z. B. eine Produktsuche.
errordataEin Problem. Normalerweise folgt ein done; wenn der Stream ohne done endet, behandeln Sie data als Fehler.
donedieselben Felder wie die JSON-AntwortDie endgültige Antwort. Ersetzen Sie den gestreamten Text durch reply.

Der Server antwortet mit einfachem JSON anstelle eines Streams, wenn Streaming für den Chatbot deaktiviert ist, wenn ein menschlicher Mitarbeiter die Unterhaltung übernimmt und bei Fehlern. Prüfen Sie den Content-Type der Antwort. Das Schließen der Verbindung stoppt die Generierung.

Chat-Verlauf

Rufen Sie die gespeicherten Nachrichten für eine Sitzung ab (beispielsweise um eine Unterhaltung nach dem Neuladen der Seite wiederherzustellen). Ein Verlauf, der älter als 30 Tage ist, wird gemäß DSGVO entfernt; eine abgelaufene Sitzung gibt 410 zurück.

GET https://webchatagent.com/api/chat/history

Query-Parameter

ParameterTypeRequiredDescription
chatbotIdstring (UUID)JaDie ID Ihres Chatbots.
sessionIdstring (UUID)JaDie Sitzung, deren Verlauf Sie abrufen möchten.

Antwort

messages ist chronologisch sortiert, beginnend mit der ältesten Nachricht. sender ist bot oder user (dies ist ein Anzeigewert, nicht die zugrunde liegende Rolle). role ist die zugrunde liegende Rolle user / assistant / system, und isAgent ist true, wenn eine assistant-Nachricht von einem menschlichen Mitarbeiter statt von der KI stammt.

{
  "messages": [
    {
      "id": 123,
      "sender": "user",
      "role": "user",
      "isAgent": false,
      "text": "What are your hours?",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": 124,
      "sender": "bot",
      "role": "assistant",
      "isAgent": false,
      "text": "Our hours are Monday to Friday, 9 AM to 5 PM.",
      "sources": [{ "type": "web", "source": "https://example.com/contact" }],
      "createdAt": "2025-01-15T10:30:01Z"
    }
  ]
}

sources ist nur vorhanden, wenn eine Nachricht Quellen enthält.

Sitzungsinformationen

Rufen Sie Nachrichtenanzahl und letzte Aktivität für Sitzungen ab, die diesem Browser bekannt sind. Um das Offenlegen von Chats anderer Besucher zu verhindern, müssen Sie die Sitzungs-IDs übergeben, die Sie bereits besitzen (z. B. aus dem lokalen Speicher). Sitzungen ohne Aktivität in den letzten 30 Tagen werden nicht zurückgegeben.

GET https://webchatagent.com/api/chat/sessions

Query-Parameter

ParameterTypeRequiredDescription
chatbotIdstring (UUID)JaDie ID Ihres Chatbots.
sessionIdsstringJaKommagetrennte Sitzungs-UUIDs (max. 5; zusätzliche werden ignoriert).

Antwort

{
  "sessions": [
    {
      "sessionId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "messageCount": 12,
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Sitzungsverlauf zurücksetzen

Löscht den In-Memory-Konversationskontext für eine Sitzung, damit die nächste Nachricht die KI ohne vorherige Interaktionen neu startet. Dadurch werden gespeicherte Nachrichten nicht gelöscht, da conversation_messages Geschäftsdaten sind und in der Datenbank verbleiben (sowie in /api/chat/history).

DELETE https://webchatagent.com/api/chat/session

Headers

HeaderRequiredDescription
X-Chat-Session-IdJaDie Sitzung, deren In-Memory-Verlauf geleert werden soll.

Antwort

{ "success": true, "message": "Chat session cleared." }

Fehlerbehandlung

Die meisten Fehler von /api/chat liefern dieselbe Struktur wie eine reguläre Antwort: eine benutzerfreundliche HTML-Nachricht in reply und ein leeres sources-Array. Der HTTP-Statuscode gibt den eigentlichen Fehlertyp an.

StatusMeaning
400Ungültiger Body, fehlendes Feld, leere Nachricht oder Nachricht mit mehr als 700 Zeichen.
403Domain nicht zulässig, Wiki-Authentifizierung fehlgeschlagen oder eine Tarifbeschränkung greift.
404Chatbot nicht gefunden.
429Rate-Limit erreicht oder das monatliche Nachrichtenkontingent ist aufgebraucht.
502Der KI-Provider (LLM) hat einen Fehler zurückgegeben.

Fehler-Antwort-Body

{
  "reply": "<p>I'm getting a lot of requests right now. Please try again in a few moments.</p>",
  "sources": []
}

Ungültige Anfragen (400), das Rate-Limit (429) und gesperrte IP-Adressen (403) geben stattdessen einen anderen Body zurück: { "error": true, "statusCode": 429, "message": "..." }. Prüfen Sie zuerst den HTTP-Statuscode und zeigen Sie dem Benutzer anschließend reply oder message an.

Rate-Limiting

ScopeLimit
Pro Sitzung10 Anfragen pro Minute
Pro IP-Adresse15 Anfragen pro Minute
Pro Sitzung und pro IP-AdresseMindestens 1 Sekunde zwischen zwei Anfragen

Wird eines der Limits überschritten, wird 429 zurückgegeben. Unabhängig davon führt auch das Erreichen des monatlichen Nachrichtenkontingents des Tarifs zu einem 429 (mit dem Hinweis "vorübergehend nicht verfügbar").

Codebeispiele

cURL

# Send a message (capture the session id from the response header)
curl -i -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you offer?",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

# Continue the conversation (reuse the session id from above)
curl -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Chat-Session-Id: SESSION_ID_FROM_FIRST_RESPONSE" \
  -d '{
    "message": "Tell me more about the premium plan",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

JavaScript / TypeScript

async function chat(message, chatbotId, sessionId = null) {
  const headers = { 'Content-Type': 'application/json' };
  if (sessionId) headers['X-Chat-Session-Id'] = sessionId;

  const response = await fetch('https://webchatagent.com/api/chat', {
    method: 'POST',
    headers,
    body: JSON.stringify({ message, chatbotId })
  });

  const data = await response.json();
  // The session id lives in the response header — keep it for follow-up messages.
  const newSessionId = response.headers.get('X-Chat-Session-Id');

  return { ...data, sessionId: newSessionId || sessionId };
}

// First message
const result = await chat('Hello!', 'YOUR_CHATBOT_ID');
console.log(result.reply);

// Follow-up in the same conversation
const followUp = await chat('Tell me more', 'YOUR_CHATBOT_ID', result.sessionId);
console.log(followUp.reply);

Python

import requests

CHATBOT_ID = "YOUR_CHATBOT_ID"
URL = "https://webchatagent.com/api/chat"

# First message
response = requests.post(URL, json={
    "message": "What are your business hours?",
    "chatbotId": CHATBOT_ID,
})

data = response.json()
session_id = response.headers.get("X-Chat-Session-Id")
print("Reply:", data["reply"])
print("Sources:", data["sources"])

# Continue the conversation
response = requests.post(
    URL,
    json={"message": "And on weekends?", "chatbotId": CHATBOT_ID},
    headers={"X-Chat-Session-Id": session_id},
)
print("Reply:", response.json()["reply"])

PHP

<?php
$chatbotId = 'YOUR_CHATBOT_ID';
$url = 'https://webchatagent.com/api/chat';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'message'   => 'What are your business hours?',
        'chatbotId' => $chatbotId,
    ]),
    CURLOPT_HEADER => true, // include headers so we can read the session id
]);

$response   = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers    = substr($response, 0, $headerSize);
$body       = json_decode(substr($response, $headerSize), true);

echo 'Reply: ' . $body['reply'] . PHP_EOL;

// Pull the session id from the response headers for follow-up messages
preg_match('/X-Chat-Session-Id:\s*(.+)/i', $headers, $matches);
$sessionId = trim($matches[1] ?? '');

curl_close($ch);

Konversationen Export-API

Exportieren Sie Ihre Chatbot-Konversationen per HTTP als CSV oder JSON, gefiltert nach Zeitraum. Nutzen Sie dies für automatische regelmäßige Berichte: Rufen Sie alle Konversationen eines Chatbots für einen bestimmten Monat ab, übergeben Sie sie an Ihre eigene Analyse oder archivieren Sie sie.

Im Gegensatz zu den oben genannten Chat-Endpunkten ist dies Teil der Dashboard-API. Sie ist nicht domain-authentifiziert. Sie melden sich mit Ihren Zugangsdaten an und verwenden das Sitzungs-Cookie für die Export-Anfrage wieder.

Authentifizierung

POST https://webchatagent.com/api/auth/login

Senden Sie Ihre E-Mail und Ihr Passwort für das Dashboard als JSON. Die Antwort setzt ein Sitzungs-Cookie; fügen Sie dieses jeder nachfolgenden Anfrage bei. Es gibt keinen separaten API-Schlüssel.

FieldTypeRequiredDescription
emailstringJaIhre Login-E-Mail für das Dashboard.
passwordstringJaIhr Dashboard-Passwort.

Voraussetzungen:

  • Verfügbar in jedem Tarif.
  • Teammitglieder benötigen die Berechtigung Konversationen.

Konversationen exportieren

GET https://webchatagent.com/api/conversations/export

Query-Parameter

ParameterTypeRequiredDescription
chatbotIdstring (UUID)NeinBeschränkt den Export auf einen Chatbot. Weglassen, um alle Chatbots zu exportieren, auf die Sie Zugriff haben.
fromstring (YYYY-MM-DD)NeinBeginn des Zeitraums, inklusive (UTC-Tagesgrenze).
tostring (YYYY-MM-DD)NeinEnde des Zeitraums, inklusive (UTC-Tagesgrenze).
qstringNeinSuchfilter. Durchsucht Sitzungs-ID, Client-IP oder Nachrichteninhalt.
formatstringNeincsv (Standard) oder json.

Eine Konversation liegt "im Zeitraum", wenn sie mindestens eine Nachricht innerhalb des Bereichs enthält. Passende Konversationen werden vollständig exportiert, einschließlich Nachrichten außerhalb des Bereichs, damit ein Transkript über Monatsgrenzen hinweg nicht abgeschnitten wird.

CSV-Format: Eine Zeile pro Nachricht, wobei die Metadaten der Konversation (Chatbot-Name, Sitzungs-ID, Nachrichtenanzahl, letzte Aktivität) in jeder Zeile wiederholt werden. Wird als Dateianhang mit einem UTF-8-BOM zurückgegeben, damit die Datei in Excel sauber geöffnet werden kann.

JSON-Format: Ein Objekt pro Konversation mit verschachtelten Nachrichten:

{
  "range": { "from": "2026-06-01T00:00:00.000Z", "to": "2026-06-30T23:59:59.000Z" },
  "sessionsCount": 42,
  "messagesCount": 314,
  "sessions": [
    {
      "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chatbotName": "Support Bot",
      "sessionId": "sess_abc123",
      "messagesCount": 6,
      "lastActivity": "2026-06-12T09:41:22.000Z",
      "lastLanguage": "de",
      "lastIp": "203.0.113.* (anon)",
      "messages": [
        {
          "role": "user",
          "content": "What are your business hours?",
          "sources": null,
          "browserLanguage": "de",
          "clientIp": "203.0.113.* (anon)",
          "referer": "https://example.com/contact",
          "createdAt": "2026-06-12T09:40:01.000Z"
        }
      ]
    }
  ]
}

Limits: Ein Export ist auf 50.000 Nachrichten begrenzt. Größere Anfragen geben 413 zurück; grenzen Sie den Zeitraum ein oder wählen Sie einen einzelnen Chatbot aus. Client-IPs werden in beiden Formaten anonymisiert.

Endpunkte für Tool-Daten

Die anderen Dashboard-Tools können über dieselbe Authentifizierung per Sitzungs-Cookie ausgelesen werden und unterstützen dieselbe Datumsfilterung mit from / to (auf dem Erstellungsdatum jedes Eintrags, UTC-Tagesgrenzen, beide inklusive). Sie geben ausschließlich JSON zurück; alle Endpunkte akzeptieren auch keine Datumsparameter, um alles zurückzugeben.

EndpointReturnsTeam permission
GET /api/questions{ success, questions: [...] }Fragen
GET /api/feedback{ success, data: [...], count }Feedback
GET /api/leads{ success, leads: [...] }Leads
GET /api/bookings[...] (einfaches Array), akzeptiert auch chatbotIdBuchungen

Im kostenlosen Tarif maskieren diese Endpunkte Inhaltsfelder (***), anstatt 403 zurückzugeben.

# All leads collected in June
curl -b cookies.txt \
  "https://webchatagent.com/api/leads?from=2026-06-01&to=2026-06-30"

Beispiel: Monatlicher Export mit cURL

# 1. Log in once and store the session cookie
curl -c cookies.txt -X POST https://webchatagent.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'

# 2. Download all June conversations of one chatbot as CSV
curl -b cookies.txt -o conversations_june.csv \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30"

# Or as JSON for automated processing
curl -b cookies.txt \
  "https://webchatagent.com/api/conversations/export?chatbotId=YOUR_CHATBOT_ID&from=2026-06-01&to=2026-06-30&format=json"

Fehlercodes

StatusMeaning
401Nicht angemeldet oder Sitzung abgelaufen. Melden Sie sich erneut an.
403Kostenloser Tarif, fehlende Konversationen-Berechtigung oder kein Chatbot-Zugriff.
404Die angegebene chatbotId existiert in Ihrem Konto nicht.
413Mehr als 50.000 Nachrichten stimmen überein. Grenzen Sie den Bereich ein oder wählen Sie einen Chatbot aus.