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-Benutzeroberfläche, eine mobile App oder eine Backend-Automatisierung zu erstellen. Jeder Endpunkt wird vom selben Origin wie Ihr Widget-Skript bereitgestellt (https://webchatagent.com).

Funktionsweise einer Konversation

1. Senden Sie die message des Benutzers und Ihre chatbotId per POST an /api/chat.
2. Lesen Sie reply aus dem JSON-Body. Lesen Sie den Antwort-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 Konversation: Nachrichtenverlauf, quellenbasierten Wissenskontext (Retrieval-Augmented Generation, RAG) und den Status für Live-Chat.
4. Wiederholen Sie diesen Vorgang. Lassen Sie den Header weg, wenn Sie eine neue Konversation beginnen möchten.

Der Server verfolgt den Verlauf pro Sitzung. Sie senden daher immer nur die neueste Nachricht, niemals das gesamte Transkript.

Authentifizierung

Die API verwendet eine domainbasierte Authentifizierung: Es gibt keinen API-Schlüssel. Jede Anfrage wird anhand von Origin/Referer der Anfrage mit den für den Chatbot konfigurierten Erlaubten Domains abgeglichen. 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 Token geben geschützte Wikis 403 zurück.

Nachricht senden

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

Headers

Request-Body

Beispielanfrage

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

Antwort

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

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

Quellen-Array (sources)

Jedes Quellenobjekt:

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: Wenn bei einem Chatbot Streaming aktiviert ist, empfängt das Widget die Antwort Token für Token über Server-Sent Events. Die hier dokumentierte reine JSON-Antwort erhalten Sie bei einer Standardanfrage. Sie ist das passende Modell für Server-zu-Server- sowie die meisten benutzerdefinierten UI-Integrationen.

Chat-Verlauf

Rufen Sie die gespeicherten Nachrichten für eine Sitzung ab (zum Beispiel, um eine Konversation nach einem Neuladen der Seite wiederherzustellen). Verläufe, die älter als 30 Tage sind, werden gemäß DSGVO entfernt; eine abgelaufene Sitzung gibt 410 zurück.

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

Query-Parameter

Antwort

messages ist chronologisch sortiert (älteste zuerst). sender ist bot oder user (dies ist ein Anzeigewert, nicht die zugrunde liegende Rolle). role ist die interne Rolle user / assistant / system, und isAgent ist true, wenn eine assistant-Nachricht von einem menschlichen Agenten 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 die Nachrichtenanzahl und die letzte Aktivität für Sitzungen ab, die diesem Browser bekannt sind. Um das Auslesen fremder Besucher-Chats zu verhindern, müssen Sie die Sitzungs-IDs übergeben, die Sie bereits besitzen (z. B. aus dem Local Storage). Sitzungen ohne Aktivität in den letzten 30 Tagen werden nicht zurückgegeben.

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

Query-Parameter

Antwort

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

Sitzungsverlauf zurücksetzen

Löschen Sie den flüchtigen Konversationskontext einer Sitzung im Arbeitsspeicher, sodass die KI bei der nächsten Nachricht neu beginnt (ohne vorherige Schritte). Dadurch werden gespeicherte Nachrichten nicht gelöscht, conversation_messages sind Geschäftsdaten und bleiben in der Datenbank (und in /api/chat/history) erhalten.

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

Headers

Antwort

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

Fehlerbehandlung

Fehler von /api/chat geben dieselbe Struktur wie eine normale Antwort zurück: eine benutzerfreundliche HTML-Nachricht in reply und ein leeres sources-Array. Der HTTP-Statuscode übermittelt den tatsächlichen Fehlertyp.

Fehlerantwort-Body

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

Der Body ist immer { reply, sources }, es gibt keine separate Fehlerstruktur. Werten Sie den HTTP-Statuscode aus und zeigen Sie dem Benutzer bei Bedarf direkt den Inhalt von reply an.

Rate-Limiting

Das Überschreiten eines dieser Limits gibt 429 zurück. Das Erreichen des monatlichen Nachrichtenkontingents des Tarifs gibt ebenfalls 429 zurück (mit dem Hinweis, dass der Dienst vorübergehend nicht verfügbar ist).

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 Exportieren API

Exportieren Sie Ihre Chatbot-Konversationen als CSV oder JSON über HTTP, gefiltert nach Zeitraum. Nutzen Sie dies, um regelmäßige Berichte zu automatisieren: Rufen Sie alle Konversationen eines Chatbots für einen bestimmten Monat ab, übergeben Sie diese an Ihre eigenen Analysetools oder archivieren Sie sie.

Im Gegensatz zu den oben genannten Chat-Endpunkten ist dies Teil der Dashboard-API. Sie ist nicht über Domains authentifiziert. Sie melden sich mit Ihren Kontozugangsdaten an und verwenden das Session-Cookie für die Exportanfrage wieder.

Authentifizierung

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

Senden Sie Ihre Dashboard-E-Mail und Ihr Passwort als JSON. Die Antwort setzt ein Session-Cookie; fügen Sie dieses in jede nachfolgende Anfrage ein. Es gibt keinen separaten API-Schlüssel.

Voraussetzungen:

• Ein kostenpflichtiger Plan. Der Export-Endpunkt gibt im kostenlosen Plan 403 zurück.
• Teammitglieder benötigen die Berechtigung Konversationen.

Konversationen exportieren

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

Query-Parameter

Eine Konversation liegt "im Zeitraum", wenn sie mindestens eine Nachricht innerhalb des Zeitraums enthält. Übereinstimmende Konversationen werden vollständig exportiert, einschließlich Nachrichten außerhalb des Zeitraums, sodass ein Transkript über eine Monatsgrenze hinweg nie 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 es sich problemlos in Excel öffnen lässt.

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.

Daten-Endpunkte für Tools

Die anderen Dashboard-Tools sind über dieselbe Session-Cookie-Authentifizierung lesbar und unterstützen dieselbe from / to Datumsfilterung (basierend auf dem Erstellungsdatum jedes Eintrags, UTC-Tagesgrenzen, jeweils inklusive). Sie geben ausschließlich JSON zurück; alle akzeptieren auch keine Datumsparameter, um alle Daten zurückzugeben.

Im kostenlosen Plan 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