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 anschliessend 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 dem Button 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 unter Quick Start (Schnellstart) bietet Ihnen ein direkt ausführbares Beispiel.

3. Geben Sie dem Schlüssel im Dialogfeld Create API Key einen Namen, legen Sie optional eine IP-Whitelist sowie ein Rate-Limit fest, wählen Sie die gewünschten Berechtigungen aus und klicken Sie anschliessend 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 beispielsweise so aus: ck_abcdefghijklmnopqrstuvwxyz012345. Jeder Schlüssel gehört genau zu 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.

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) - ermöglicht den Zugriff auf die Endpunkte /v1/chat und /v1/chat/stream.
• Conversation history (list and read past conversations) - 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

Sendet eine Nachricht an den Bot und empfängt die vollständige Antwort in einer einzigen JSON-Rückgabe.

Anfrage-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 Konversation anzuknüpfen.
• metadata - optionales Objekt: {source, userName, userEmail, userPhone}. userEmail wird auch zur Ableitung der internen Client-ID verwendet.

Antwort-Body (200)

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

• message.role ist immer "assistant"; message.content enthält die vollständige Antwort.
• model ist die Modell-ID, mit der der Bot diesen Aufruf ausgeführt hat.
• usage.creditsUsed berücksichtigt die Nutzernachricht + Bot-Antwort (in der Regel 2) zuzüglich eines zusätzlichen Credit pro ausgeführtem Tool-Aufruf.
• actions listet die während dieses Durchlaufs ausgeführten Tools auf. 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.

Anfrage-Body

Gleicher Aufbau wie bei POST /v1/chat. Das Flag stream im Body ist nicht erforderlich - das Verwenden dieses Pfades aktiviert SSE automatisch.

Antwort-Body (SSE-Events)

• message.delta - Inhaltsfragment { "content": "..." }. Mehrere dieser Fragmente werden gestreamt, sobald Tokens eintreffen.
• action - Tool-Ausführung { "type", "name", "status": "executing" }. Wird ausgegeben, wenn der Bot einen Funktionsaufruf auslöst.
• message.done - Abschluss-Event mit conversationId, model, usage und (sofern vorhanden) der Liste der abgeschlossenen actions.
• error - wird gesendet, wenn die Generierung fehlschlägt; der Stream wird danach beendet.

Bei längeren Generierungen werden alle 15 Sekunden Keep-Alive-SSE-Kommentare (:keepalive) gesendet. Serverseitige Timeouts: 30 Sekunden für das erste Token, maximal 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 an Ihren Schlüssel gebundenen Bot über alle Quellen hinweg auf (Widget, WhatsApp, API usw.).

Query-Parameter

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

Antwort-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 nach 100 Zeichen abgeschnitten und mit ... versehen.
• nextCursor ist auf der letzten Seite null; übergeben Sie ihn als cursor, um die nächste Seite abzurufen.

GET /v1/conversations/{conversation_id}

Vollständiger Konversationsverlauf.

Antwort-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, wenn die Konversation nicht zu dem an Ihren Schlüssel gebundenen Bot gehört.

Verwenden Sie zur Überprüfung der Bot-Konfiguration 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ässig 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 verwenden eine einheitliche Struktur:

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

Häufige HTTP-Statuscodes:

• 400 invalid_request_error - fehlerhafte Eingabe (Codes: invalid_parameter, 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-Adresse blockiert (ip_blocked), IP-Adresse 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 - Konversation gehört nicht zu diesem Bot
• 405 invalid_request_error (method_not_allowed) - falsche HTTP-Methode 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.