Bot Talk API

Bot Talk API

Die Bot Talk API ist eine REST-API für die Kommunikation mit einem bestimmten Chatbot aus Ihrer eigenen Anwendung heraus - etwa über benutzerdefinierte Apps, interne Tools oder selbst erstellte Automatisierungen. Sie erstellen einen API-Schlüssel im Tab API des Bots und rufen anschließend den Chat-Endpunkt mit dem Schlüssel als Bearer-Token auf, um die Antworten des Bots zu erhalten - entweder als einzelne Antwort oder als Stream über SSE.

Erste Schritte

1. Wählen Sie Ihren Chatbot aus und navigieren Sie oben auf der Bot-Seite zum Tab API (Select Bot > API - Bot auswählen > API).

2. Klicken Sie auf Create API Key (API-Schlüssel erstellen).

Der Zähler neben der Schaltfläche zeigt an, wie viele Schlüssel aktiv sind („1 of 5 API keys active“). Der Link View API Documentation (API-Dokumentation anzeigen) öffnet diese Referenz, und das curl-Snippet Quick Start (Schnellstart) bietet Ihnen ein direkt ausführbares Beispiel.

3. Vergeben Sie im Dialogfeld Create API Key einen Namen für den Schlüssel, legen Sie optional eine IP-Whitelist sowie ein Ratenlimit fest, wählen Sie die Berechtigungen aus und klicken Sie dann auf Create (Erstellen).

4. Kopieren Sie den vollständigen Schlüssel aus dem Bestätigungsdialog. Der Klartext wird nur ein einziges Mal angezeigt.

Ein Schlüssel sieht wie folgt aus: ck_abcdefghijklmnopqrstuvwxyz012345. Jeder Schlüssel gehört zu genau diesem einen Bot, sodass jede mit dem Schlüssel gesendete Anfrage diesen Bot anspricht - der Bot wird über den Schlüssel identifiziert und erscheint nie in der URL.

5. Führen Sie von Ihrem Server aus das unten stehende curl-Beispiel mit Ihrem Schlüssel und einer kurzen Testnachricht aus. Speichern Sie die zurückgegebene conversationId und verwenden Sie sie für eine Folgeanfrage erneut. Bestätigen Sie die Antwort und die Konversation im Tab Chatlogs des Bots.

Bewahren Sie ck_-Schlüssel auf Ihrem Server auf und niemals im JavaScript einer Website oder in Bundles mobiler Apps. Die Berechtigung „Conversations“ gewährt Zugriff auf die gespeicherten Konversationen aller Besucher dieses Bots, daher muss Ihre Anwendung jeden Endnutzer autorisieren, bevor diese Daten zurückgegeben werden. Verwenden Sie im API-Tab Revoke (Widerrufen) oder Delete (Löschen), um einen Schlüssel außer Betrieb zu nehmen; bei keiner der Aktionen wird der Klartext erneut angezeigt.

Erstellen und trainieren Sie Ihren Chatbot vor dem Start und prüfen Sie, ob Ihr Konto API-Zugriff beinhaltet und über Nachrichten-Credits verfügt.

Basis-URL

https://api.chatlab.com/aichat

Alle Endpunkte in diesem Artikel beziehen sich auf diese Basis-URL.

Schlüsselberechtigungen

Jeder Schlüssel enthält eine oder beide der folgenden Berechtigungen, die über die Schalter im Dialogfeld Create API Key festgelegt werden:

• Chat (send messages and receive responses) (Nachrichten senden und Antworten empfangen) - ermöglicht den Zugriff auf die Endpunkte /v1/chat und /v1/chat/stream.
• Conversation history (list and read past conversations) (Vergangene Unterhaltungen auflisten und lesen) - ermöglicht den Zugriff auf die /v1/conversations-Endpunkte.

Im API-Tab werden die erteilten Berechtigungen jedes Schlüssels als Badges für Chat und Conversations angezeigt.

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage im Authorization-Header mit:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Anfragen ohne den Header Authorization: Bearer ... geben 401 missing_api_key zurück. Unbekannte Schlüssel geben 401 invalid_api_key zurück; widerrufene Schlüssel geben 401 revoked_api_key zurück. Bei fünf ungültigen Versuchen innerhalb einer Minute von derselben IP-Adresse wird eine 60-minütige Sperre aktiviert.

Limits

• Maximal 5 aktive Bot-Talk-Schlüssel pro Bot
• Maximal 60 Anfragen pro Minute und Schlüssel (Token-Bucket, Kapazität 60, kontinuierliches Nachfüllen mit 1 Token pro Sekunde). Bei der Erstellung nach unten anpassbar - legen Sie ein niedrigeres rateLimitPerMinute fest, sinkt die Obergrenze und die Nachfüllrate skaliert entsprechend mit.
• Maximale Nachrichtenlänge: 4.000 Zeichen
• Die Anzahl gleichzeitiger SSE-Streams pro Schlüssel unterliegt den Limits Ihres Kontos

Endpunkte

POST /v1/chat

Senden Sie eine Nachricht an den Bot und erhalten Sie die vollständige Antwort in einer einzigen JSON-Response.

Request-Body

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}

• message - erforderlicher String, maximal 4.000 Zeichen.
• conversationId - optionale UUID. Für eine neue Konversation weglassen; verwenden Sie den zuvor vom Server zurückgegebenen Wert wieder, um an eine bestehende anzuknüpfen.
• metadata - optionales Objekt, das {source, userName, userEmail, userPhone} akzeptiert. Derzeit wird hier nur userEmail verwendet, um die Client-Kennung abzuleiten; der Kanal wird als API erfasst. Verlassen Sie sich nicht darauf, dass die anderen Metadatenfelder in einem Lead-Datensatz gespeichert werden.

Response-Body (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}

• message.role ist immer "assistant"; message.content ist die vollständige Antwort.
• model ist die Modell-ID, auf der der Bot für diesen Aufruf lief.
• usage.creditsUsed meldet derzeit 2 plus eins pro gemeldetem Tool-Aufruf für einen abgeschlossenen Turn. Dieser Response-Zähler enthält keine Modell-/Kontext-Credit-Multiplikatoren und darf nicht als Abrechnungsgrundlage verwendet werden. Nutzen Sie Nutzungsdaten der Management API für den Account-Verbrauch und lesen Sie Nachrichten-Credits.
• actions listet Tool-Ausführungen auf, die während dieses Turns liefen. Aktuell werden nur function_call-Einträge ausgegeben (mit type, name, status: "completed").

POST /v1/chat/stream

Streaming-Variante von /v1/chat. Gibt Content-Type: text/event-stream mit Server-Sent Events zurück.

Request-Body

Gleicher Aufbau wie POST /v1/chat. Das Flag stream im Body ist nicht erforderlich - die Verwendung dieses Pfads löst SSE aus.

Response-Body (SSE-Events)

• message.reset - verwirft den für die aktuelle Antwort angesammelten Text und beginnt erneut mit dem Sammeln von Deltas. Dies kann auftreten, wenn die Generierung neu startet; das Anhängen beider Versionen würde eine doppelte oder überholte Antwort anzeigen.
• message.delta - Inhaltsfragment { "content": "..." }. Mehrere davon werden gestreamt, sobald Tokens eintreffen.
• action - Tool-Ausführung { "type", "name", "status": "executing" }. Wird ausgegeben, wenn der Bot einen Funktionsaufruf auslöst.
• message.done - abschließendes Event mit conversationId, model, usage und (falls vorhanden) der Liste abgeschlossener Aktionen (actions).
• error - wird gesendet, wenn die Generierung fehlschlägt; der Stream bricht danach ab.

Keep-Alive-SSE-Kommentare (:keepalive) werden bei langen Generierungen alle 15 Sekunden gesendet. Serverseitige Timeouts: 30 Sekunden für das erste Token, insgesamt 120 Sekunden pro Stream.

cURL-Beispiel

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Listet Konversationen für den Bot auf, der an Ihren Schlüssel gebunden ist - über alle Quellen hinweg (Widget, WhatsApp, API usw.).

Query-Parameter

• limit - 1-100, Standardwert 20. Werte außerhalb dieses Bereichs werden begrenzt.
• cursor - opaker Wert, der auf der vorherigen Seite in nextCursor zurückgegeben wurde. Für die erste Seite weglassen.

Response-Body (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

• lastMessagePreview wird mit dem Suffix ... auf 100 Zeichen gekürzt.
• nextCursor ist auf der letzten Seite null; übergeben Sie diesen Wert als cursor, um die nächste abzurufen.

GET /v1/conversations/{conversation_id}

Gespeicherte Konversationsnachrichten, die über diesen Endpunkt bereitgestellt werden.

Response-Body (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Es werden nur die Rollen user und assistant zurückgegeben; interne system- und Tool-Nachrichten werden herausgefiltert. Gibt 404 not_found_error zurück, falls die Konversation nicht zu dem Bot gehört, der an Ihren Schlüssel gebunden ist.

Um die Bot-Konfiguration einzusehen, verwenden Sie den Management-API-Endpunkt GET /v1/management/bots/{bot_id} mit einem Management-Schlüssel.

Rate-Limit-Header

Antworten, die die Rate-Limit-Prüfung erreichen (d. h. Authentifizierung und IP-Whitelist wurden erfolgreich durchlaufen), enthalten folgende Header:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - das für diesen Aufruf tatsächlich angewendete Limit pro Schlüssel (standardmäßig 60 oder Ihr konfiguriertes rateLimitPerMinute, falls niedriger).
• X-RateLimit-Remaining - verbleibende Tokens im Bucket unmittelbar nach diesem Aufruf.
• X-RateLimit-Reset - Unix-Zeitstempel in Sekunden, an dem das nächste Token verfügbar wird (kein vollständiger Bucket-Reset; der Bucket füllt sich kontinuierlich auf). Wenn der Bucket voll ist, entspricht dies der aktuellen Zeit.

Bei 429 rate_limit_exceeded-Antworten wird zusätzlich Retry-After gesetzt, angegeben in ganzen Sekunden, bis mindestens ein Token wieder frei wird.

Fehler vor der Authentifizierung (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) und 403 ip_not_whitelisted enthalten keine X-RateLimit-*-Header - der Limiter wird erst nach erfolgreicher Authentifizierung und IP-Prüfung abgefragt.

Fehlerformat

Alle Fehler nutzen dieselbe Hülle:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Gängige HTTP-Codes:

• 400 invalid_request_error - fehlerhafte Eingabe (invalid_parameter)
• 415 invalid_request_error - nicht unterstützter Content-Type (unsupported_media_type)
• 401 authentication_error - fehlender Schlüssel (missing_api_key), unbekannter Schlüssel (invalid_api_key) oder widerrufener Schlüssel (revoked_api_key)
• 402 quota_exceeded_error - Nachrichten-Credits aufgebraucht
• 403 permission_error - IP blockiert (ip_blocked), IP nicht in der Whitelist des Schlüssels (ip_not_whitelisted) oder Schlüsseltyp erlaubt diesen Endpunkt nicht (key_type_not_allowed, insufficient_permissions)
• 404 not_found_error - Unterhaltung gehört nicht zu diesem Bot
• 405 invalid_request_error (method_not_allowed) - falsches HTTP-Verb für die URL
• 429 rate_limit_error - zu viele Anfragen (rate_limit_exceeded) oder zu viele gleichzeitige Streams (concurrent_streams_exceeded)
• 500 api_error - interner Fehler

Verwandte Themen

Informationen zu Vorgängen auf Kontoebene (Erstellen von Bots, Aktualisieren von Bots, Abrufen von Nutzungsdaten) finden Sie unter Management API.