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
- Senden Sie die
messagedes Benutzers und IhrechatbotIdper POST an/api/chat. - Lesen Sie die
replyaus dem JSON-Body. Lesen Sie den Response-HeaderX-Chat-Session-Id, das ist Ihre Sitzungs-ID. - 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. - 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
| Header | Required | Description |
|---|---|---|
Content-Type | Ja | Muss application/json sein. |
X-Chat-Session-Id | Nein | Sitzungs-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. |
Accept | Nein | text/event-stream, um die Antwort als Stream zu empfangen (siehe Streaming). |
Accept-Language | Nein | Bevorzugte Sprache für die Antwort, z. B. de. |
Request Body
| Feld | Type | Required | Description |
|---|---|---|---|
message | string | Ja | Die Nachricht des Benutzers. Maximal 700 Zeichen. Darf nicht leer sein. |
chatbotId | string (UUID) | Ja | Die ID Ihres Chatbots aus den Einstellungen des Chatbots. |
pageUrl | string | Nein | Die 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. |
contextData | object | Nein | Flacher 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.
| Feld | Type | Description |
|---|---|---|
reply | string | Die 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. |
sources | array | Quellen, auf denen die Antwort basiert (siehe unten). Leer, falls keine verwendet wurden. |
mode | string | Modus der Unterhaltung: bot (KI antwortet) oder human (ein menschlicher Mitarbeiter hat übernommen). Vorhanden, wenn relevant. |
status | string | Live-Chat-Status: waiting, open oder closed. Nur vorhanden, wenn Live-Chat für die Sitzung aktiv ist. |
aiGenerated | boolean | true, wenn die KI die Antwort verfasst hat. Fehlt, während ein menschlicher Mitarbeiter die Unterhaltung führt. |
conversationTooLong | boolean | Die 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:
| Feld | Type | Description |
|---|---|---|
type | string | web (eine Webseite), product (strukturierte Produktdaten) oder fileSource (ein Dokument aus einem verbundenen Dateispeicher). |
source | string | Für web: die Seiten-URL. Für product: die Produktkennung. Für fileSource: die Dokument-ID. |
data | object | Nur 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}
type | Felder | Bedeutung |
|---|---|---|
token | data | Nächster Teil der Antwort. Hängen Sie ihn an. Der Text kann unvollständiges Markdown und den Anfang des Vorschlagskommentars enthalten. |
tool_call | name | Der Bot verwendet ein Tool, z. B. eine Produktsuche. |
error | data | Ein Problem. Normalerweise folgt ein done; wenn der Stream ohne done endet, behandeln Sie data als Fehler. |
done | dieselben Felder wie die JSON-Antwort | Die 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
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | Ja | Die ID Ihres Chatbots. |
sessionId | string (UUID) | Ja | Die 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
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | Ja | Die ID Ihres Chatbots. |
sessionIds | string | Ja | Kommagetrennte 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
| Header | Required | Description |
|---|---|---|
X-Chat-Session-Id | Ja | Die 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.
| Status | Meaning |
|---|---|
400 | Ungültiger Body, fehlendes Feld, leere Nachricht oder Nachricht mit mehr als 700 Zeichen. |
403 | Domain nicht zulässig, Wiki-Authentifizierung fehlgeschlagen oder eine Tarifbeschränkung greift. |
404 | Chatbot nicht gefunden. |
429 | Rate-Limit erreicht oder das monatliche Nachrichtenkontingent ist aufgebraucht. |
502 | Der 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
| Scope | Limit |
|---|---|
| Pro Sitzung | 10 Anfragen pro Minute |
| Pro IP-Adresse | 15 Anfragen pro Minute |
| Pro Sitzung und pro IP-Adresse | Mindestens 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.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Ja | Ihre Login-E-Mail für das Dashboard. |
password | string | Ja | Ihr 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
| Parameter | Type | Required | Description |
|---|---|---|---|
chatbotId | string (UUID) | Nein | Beschränkt den Export auf einen Chatbot. Weglassen, um alle Chatbots zu exportieren, auf die Sie Zugriff haben. |
from | string (YYYY-MM-DD) | Nein | Beginn des Zeitraums, inklusive (UTC-Tagesgrenze). |
to | string (YYYY-MM-DD) | Nein | Ende des Zeitraums, inklusive (UTC-Tagesgrenze). |
q | string | Nein | Suchfilter. Durchsucht Sitzungs-ID, Client-IP oder Nachrichteninhalt. |
format | string | Nein | csv (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.
| Endpoint | Returns | Team 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 chatbotId | Buchungen |
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
| Status | Meaning |
|---|---|
401 | Nicht angemeldet oder Sitzung abgelaufen. Melden Sie sich erneut an. |
403 | Kostenloser Tarif, fehlende Konversationen-Berechtigung oder kein Chatbot-Zugriff. |
404 | Die angegebene chatbotId existiert in Ihrem Konto nicht. |
413 | Mehr als 50.000 Nachrichten stimmen überein. Grenzen Sie den Bereich ein oder wählen Sie einen Chatbot aus. |
