← Zurück zur App

API & MCP

Steuern Sie Ihren Chatbot aus Ihrem eigenen Code oder über KI-Assistenten.

Überblick#

Chatbotty kann auf zwei Wegen außerhalb des Dashboards genutzt und verwaltet werden: über die REST API für Ihren eigenen Code und über den MCP-Connector für KI-Assistenten wie Claude. Beide arbeiten jeweils mit einem Chatbot und verwenden dieselben API-Schlüssel. Beginnen Sie mit Authentifizierung.

Grundlagen

PunktWert
REST-Basis-URLhttps://www.chatbotty.ai/api/v1
MCP-Server-URLhttps://www.chatbotty.ai/api/mcp
FormatJSON über HTTPS
AuthentifizierungAuthorization: Bearer YOUR_API_KEY
Geltungsbereich eines SchlüsselsEin Schlüssel gehört genau zu einem Chatbot; der Chatbot wird nie in der Anfrage gesendet, sondern aus dem Schlüssel abgeleitet

Was Sie verwenden sollten

  • REST API - Sie schreiben Code, der Chatnachrichten sendet oder Dokumente, Konversationen, Tickets und Webhook-Aktionen verwaltet. Siehe Chatbot und die folgenden Abschnitte zu den Endpunkten.
  • MCP-Connector - Sie verbinden einen KI-Assistenten und lassen ihn ohne Programmierung mit dem Chatbot arbeiten. Siehe MCP-Connector und MCP-Clients.

Tarife

API-Schlüssel, die REST API und der MCP-Connector sind in jedem Tarif verfügbar: Free, Evaluation, Support und Automate. Einzelne Funktionen hängen vom Tarif ab.

FunktionFreeEvaluationSupportAutomate
Chat, Dokumente, Konversationen, AnalysenJaJaJaJa
TicketsNeinJaJaJa
Webhook-AktionenNeinJaNeinJa
Dokumentimport von einer Web-URLNeinJaJaJa

Ein Aufruf einer Funktion, die nicht in Ihrem Tarif enthalten ist, liefert 403 FORBIDDEN. Der MCP-Connector bietet solche Tools gar nicht erst an. Ein Tarifwechsel gilt ab der nächsten Anfrage.

Kontingent

  • Nur über Chat gesendete Nachrichten (REST POST /chat oder das MCP-Tool send_message) werden auf das monatliche Nachrichtenkontingent angerechnet, genau wie Widget-Nachrichten.
  • Andere Aufrufe (Dokumente, Konversationen, Analysen, Tickets, Webhook-Aktionen) verbrauchen das Kontingent nicht.
  • Ist das Kontingent aufgebraucht, liefert der Chat-Aufruf 403 QUOTA_EXCEEDED. Das verbleibende Kontingent prüfen Sie mit GET /chatbot.
  • Schlüssel funktionieren unabhängig von den erlaubten Domains des Chatbots und auch dann, wenn der Chatbot für das Widget inaktiv ist (außer beim Senden von Chatnachrichten, die ein inaktiver Chatbot mit 404 NOT_FOUND ablehnt).

Antwortformat

Jede REST-Antwort verwendet denselben Umschlag. Fehler sind unter Fehler beschrieben.

{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }

Authentifizierung#

Jede Anfrage muss einen API-Schlüssel des Chatbots als Bearer-Token enthalten. Derselbe Schlüssel funktioniert für die REST API und für den MCP-Connector.

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot

API-Schlüssel

PunktWert
FormatEine zufällige hexadezimale Zeichenfolge mit 64 Zeichen
GeltungsbereichEin Chatbot pro Schlüssel
LimitBis zu 50 Schlüssel pro Chatbot (inaktive Schlüssel zählen mit)
SpeicherungNur ein Hash wird gespeichert; der vollständige Schlüssel wird einmal angezeigt, direkt nach der Erstellung

Behandeln Sie Schlüssel wie Passwörter: Geben Sie sie nie weiter und verwenden Sie sie nie in clientseitigem Code.

Schlüssel im Dashboard verwalten

  1. Öffnen Sie API & MCP in der Seitenleiste.
  2. Klicken Sie auf der Karte Ihres Chatbots auf Neuen API-Schlüssel erstellen, geben Sie einen Namen ein (zum Beispiel „Production app“) und klicken Sie auf Erstellen.
  3. Kopieren Sie den Schlüssel sofort. Er kann nicht erneut angezeigt werden („Copy this key now. You won't be able to see it again.“).

Danach zeigt die Liste den Namen des Schlüssels, seine ersten 12 Zeichen und Zuletzt verwendet.

AktionWirkung
DeaktivierenDer Schlüssel funktioniert sofort nicht mehr; Aktivieren schaltet ihn wieder ein
LöschenDer Schlüssel wird dauerhaft entfernt; Anwendungen, die ihn nutzen, funktionieren sofort nicht mehr

Schlüssel, die beim Verbinden eines KI-Assistenten erstellt wurden, sind mit MCP-Connector gekennzeichnet. Das Löschen eines solchen Schlüssels trennt den Assistenten. Verbinden Sie denselben Assistenten erneut mit demselben Chatbot, ersetzt das seinen alten Schlüssel.

Authentifizierungsfehler

SituationAntwort
Header fehlt oder ist fehlerhaft401 UNAUTHORIZED „Missing or invalid Authorization header“
Unbekannter oder deaktivierter Schlüssel401 UNAUTHORIZED „Invalid or inactive API key“

Alle Codes finden Sie unter Fehler, die Anfragelimits unter Rate Limits.

Rate Limits#

Die Limits gelten pro API-Schlüssel und pro Minute. Jede Klasse von Endpunkten hat einen eigenen Zähler, sodass viele Schreibzugriffe das Budget für Lesezugriffe nicht aufbrauchen.

REST API

KlasseEndpunkteLimit pro Minute
ChatPOST /chat60
LesenAlle anderen GET-Endpunkte außer Analysen (einschließlich GET /chatbot)120
SchreibenPOST-, PATCH-, DELETE-Endpunkte60
AnalysenGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Webhook-TestPOST /webhooks/{id}/test20

Zusätzliches Limit: POST /documents/upload-url stellt pro Chatbot innerhalb von 2 Stunden höchstens 50 Upload-URLs aus.

MCP-Connector

Der MCP-Endpunkt erlaubt 300 Anfragen pro Minute und Schlüssel. Jeder Tool-Aufruf unterliegt dann zusätzlich dem REST-Limit des Endpunkts, den er nutzt, und send_message verbraucht das Nachrichtenkontingent.

Wenn Sie ein Limit überschreiten

Die API liefert 429 RATE_LIMITED mit einer Meldung wie „Rate limit exceeded. Maximum 60 requests per minute per API key.“ Warten Sie bis zur nächsten Minute und versuchen Sie es erneut, idealerweise mit wachsender Verzögerung.

Rate Limits sind vom monatlichen Nachrichtenkontingent getrennt; siehe Überblick und Fehler.

Chatbot#

Identifizieren Sie den Chatbot, zu dem Ihr API-Schlüssel gehört, und prüfen Sie seinen Tarif und sein Kontingent, bevor Sie mit ihm arbeiten.

GET /chatbot

PunktWert
Methode und PfadGET https://www.chatbotty.ai/api/v1/chatbot
ParameterKeine
Rate LimitKlasse Lesen (siehe Rate Limits)
KontingentNicht verbraucht
MCP-Toolget_chatbot_info

Antwort

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "CycleZone",
    "description": "Customer care chatbot",
    "is_active": true,
    "language": "auto",
    "timezone": "America/New_York",
    "handoff_contact": "info@example.com",
    "created_at": "2026-01-01T10:00:00.000Z",
    "dashboard_url": "https://www.chatbotty.ai/dashboard/chatbots/uuid",
    "plan": "Automate",
    "message_quota": { "used": 622, "monthly_limit": 9000, "extra_messages": 0 },
    "features": { "tickets": true, "upload_from_url": true, "webhook_actions": true },
    "knowledge_base": {
      "documents_total": 1,
      "documents_by_status": { "pending": 0, "processing": 0, "completed": 1, "failed": 0 },
      "last_updated_at": "2026-01-01T10:00:00.000Z"
    }
  }
}

Hinweise

  • plan und message_quota gehören zum Kontoinhaber; das Kontingent wird von allen Chatbots des Kontos geteilt.
  • features zeigt, welche tarifabhängigen Funktionen dieser Schlüssel nutzen kann.
  • handoff_contact ist der Kontakt, den der Chatbot nennt, wenn er die Antwort nicht kennt (hier schreibgeschützt; null, wenn nicht gesetzt).
  • last_updated_at ist der Zeitpunkt des neuesten hochgeladenen Dokuments.

Chat#

Senden Sie eine Nachricht an den Chatbot und erhalten Sie seine Antwort, genau wie ein Besucher im Widget.

POST /chat

PunktWert
Methode und PfadPOST https://www.chatbotty.ai/api/v1/chat
Rate LimitKlasse Chat: 60 pro Minute
KontingentEine Nachricht pro Aufruf; über dem Kontingent liefert der Aufruf 403 QUOTA_EXCEEDED
MCP-Toolsend_message

Anfragekörper

FeldErforderlichBeschreibung
messageJaDie Frage des Besuchers (nicht leerer Text)
conversation_idNeinSetzt eine bestehende Konversation fort; weglassen, um eine neue zu starten
optionsNeinOptionales Objekt; für die normale Nutzung nicht nötig

Existiert conversation_id nicht oder gehört zu einem anderen Chatbot, liefert der Aufruf 400 CONVERSATION_NOT_FOUND. Ein Chatbot, der nicht aktiv ist, liefert 404 NOT_FOUND.

Antwort

{
  "success": true,
  "data": {
    "message": "Our warranty is two years.",
    "conversation_id": "uuid",
    "sources": [{ "content": "...", "similarity": 0.87 }],
    "metadata": {
      "tokensUsed": 312,
      "cached": false,
      "responseTime": 1240,
      "searchResults": 3,
      "quality": "answered",
      "confidence": 0.87,
      "tools_executed": [{ "name": "get_weather", "ok": true }]
    }
  }
}

Konversationskontext

Der erste Aufruf erstellt eine Konversation und liefert ihre conversation_id. Senden Sie diese ID mit jeder folgenden Nachricht, um den Kontext zu behalten. Über die API erstellte Konversationen erscheinen im Dashboard mit der Quelle api.

tools_executed

metadata.tools_executed listet die Tools auf, die der Chatbot beim Antworten aufgerufen hat (Webhook-Aktionen, Erstellung von Support-Tickets). Jeder Eintrag hat name, ok und bei einem Fehler einen kurzen code wie webhook_timeout, webhook_redirect, webhook_blocked oder invalid_args. Eine leere Liste bedeutet, dass kein Tool aufgerufen wurde. Nutzen Sie sie, um zu prüfen, ob eine Webhook-Aktion wirklich ausgeführt wurde.

Dokumente#

Verwalten Sie die Wissensdatenbank des Chatbots: Dokumente hochladen, lesen, bearbeiten, auflisten und löschen. Diese Aufrufe verbrauchen das Nachrichtenkontingent nicht.

Endpunkte

Methode und PfadBeschreibungWichtige ParameterMCP-Tool
GET /documentsDokumente auflistenlimit (Standard 20, max. 100), offset, statuslist_documents
POST /documentsEin Dokument hochladen; liefert 202Siehe untenupload_document
POST /documents/upload-urlEine signierte URL für eine große oder lokale Datei abrufenfilenamecreate_upload_url
GET /documents/{id}Status und Details eines Dokuments-get_document
DELETE /documents/{id}Ein Dokument löschen-delete_document
GET /documents/{id}/contentDen Text seitenweise lesenoffset, limit (Standard 20000, max. 50000)read_document
PATCH /documents/{id}/contentEin .md- oder .txt-Dokument bearbeitenedits, append, expected_hashedit_document, append_to_document

Limits: GET-Aufrufe nutzen das Lese-Limit, die anderen das Schreib-Limit (siehe Rate Limits).

Upload

Erlaubte Typen: .pdf, .docx, .txt, .md, bis 10 MB. Senden Sie entweder multipart/form-data oder JSON.

FeldBeschreibung
fileDie Datei (nur multipart)
contentText eines .md- oder .txt-Dokuments (JSON; filename erforderlich)
content_base64Binärdatei in Base64 (JSON; bis etwa 3 MB verwenden)
urlÖffentliche Datei-URL, die der Server herunterlädt (JSON; nur Tarife mit Web-URL-Import)
upload_idID aus POST /documents/upload-url, nachdem Sie die Datei hochgeladen haben
filenameDateiname mit Erweiterung
descriptionOptionale Beschreibung
replace_existingStandard true: Eine Datei mit demselben Namen wird durch die neue Version ersetzt

Senden Sie in JSON genau eines von content, content_base64, url, upload_id.

{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }

Große oder lokale Dateien

  1. POST /documents/upload-url mit { "filename": "price-list.pdf" }. Die Antwort enthält upload_id, upload_url und Header; die URL ist 2 Stunden gültig und funktioniert einmal.
  2. Senden Sie die Rohdatei per PUT an upload_url.
  3. POST /documents mit { "upload_id": "...", "filename": "price-list.pdf" }.

Verarbeitung und Status

Die Verarbeitung ist asynchron. Der Status wechselt von pending über processing zu completed oder endet als failed mit einer error_message. Ein fehlgeschlagenes Dokument bleibt in der Liste; löschen Sie es oder laden Sie es erneut hoch. Fragen Sie GET /documents/{id} wiederholt ab, bis completed erreicht ist.

Bearbeiten und ersetzen

  • PATCH /documents/{id}/content sendet nur die Änderung: edits (Liste aus old_text und new_text, jeder old_text muss genau einmal vorkommen, bis zu 100) und/oder append (text, optional after_heading).
  • expected_hash (aus GET .../content) schützt davor, eine neuere Version zu überschreiben (409 CONFLICT).
  • Nur UTF-8-Dokumente .md und .txt können bearbeitet werden (sonst 400 NOT_EDITABLE).
  • Jede Bearbeitung oder Ersetzung erzeugt eine neue document_id; die alte Version antwortet weiter, bis die neue completed ist.
  • Eine zweite Änderung, während das Dokument noch verarbeitet wird, liefert 409 REPLACE_IN_PROGRESS.

Konversationen#

Lesen Sie den Konversationsverlauf des Chatbots, einschließlich der im Widget erstellten Konversationen. Diese Aufrufe sind schreibgeschützt und verbrauchen das Nachrichtenkontingent nicht.

Endpunkte

Methode und PfadBeschreibungWichtige ParameterMCP-Tool
GET /conversationsKonversationen auflistenSiehe untenlist_conversations
GET /conversations/{id}Eine Konversation-get_conversation
GET /conversations/{id}/messagesNachrichten in chronologischer Reihenfolgelimit (Standard 50, max. 200), offsetget_conversation_messages

Alle drei nutzen das Lese-Limit von 120 Anfragen pro Minute (siehe Rate Limits). Eine Konversation eines anderen Chatbots liefert 404 NOT_FOUND.

Listenfilter

ParameterBeschreibung
limit, offsetSeitenaufteilung (Standard 20, max. 100)
statusactive, completed oder ticket_created
sourcewidget oder api
from, toISO-8601-Daten; filtern nach dem Beginn der Konversation
qualityKonversationen mit mindestens einer Frage dieser Art: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qVolltextsuche im Nachrichtentext (2 bis 200 Zeichen)

Antwort

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "uuid",
        "started_at": "2026-01-01T10:00:00Z",
        "last_activity_at": "2026-01-01T10:15:00Z",
        "message_count": 5,
        "status": "active",
        "source": "widget",
        "email": "visitor@example.com",
        "phone": null
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "total": 42 }
  }
}

In Tarifen mit Tickets enthalten die Details einer Konversation zusätzlich die in ihr erstellten tickets. Nachrichten haben id, role (user oder assistant), content und created_at.

Tipp

Um Fragen zu finden, die der Chatbot nicht beantworten konnte, verwenden Sie GET /analytics/top-queries?quality=not_answered (siehe Analysen) und öffnen Sie die zugehörigen Konversationen über conversation_ids.

Analysen#

Aggregierte Statistiken des Chatbots. Analysen sind in jedem Tarif verfügbar, auch in Free. Diese Aufrufe verbrauchen das Nachrichtenkontingent nicht.

Endpunkte

Methode und PfadBeschreibungMCP-Tool
GET /analytics/summarySummen für den Zeitraumget_analytics_summary
GET /analytics/timeseriesAnzahlen pro Stunde, Tag oder Wocheget_analytics_timeseries
GET /analytics/top-queriesHäufigste Fragenget_top_queries, list_knowledge_gaps

Alle drei nutzen das Analysen-Limit von 60 Anfragen pro Minute (siehe Rate Limits).

Gemeinsame Parameter

ParameterBeschreibung
periodtoday (Standard), week, month oder quarter, ausgewertet in der Zeitzone des Chatbots
from, toISO-8601-Daten; sie ersetzen period; der Bereich beträgt höchstens 366 Tage
sourcewidget oder api

Zusätzliche Parameter

EndpunktParameterBeschreibung
timeseriesgranularityauto (Standard), hour, day oder week; hour mit quarter wird abgelehnt
top-querieslimit, offsetSeitenaufteilung (Standard 20, max. 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Antwort von summary

{
  "period": "week",
  "total_queries": 7,
  "answered_queries": 5,
  "not_answered_queries": 1,
  "conversation_queries": 1,
  "off_topic_queries": 0,
  "ticket_created_queries": 0,
  "tool_call_queries": 0,
  "success_rate": 83.3,
  "widget_queries": 6,
  "api_queries": 1
}

success_rate ist beantwortet geteilt durch beantwortet plus nicht beantwortet, in Prozent.

Unbeantwortete Fragen

GET /analytics/top-queries?quality=not_answered&period=month liefert die Fragen, die der Chatbot nicht beantworten konnte, die häufigsten zuerst. Jeder Eintrag hat content, count, last_asked und bis zu 5 conversation_ids, die Sie über die Konversationen öffnen können. Ergänzen Sie die fehlenden Fakten in der Wissensdatenbank und prüfen Sie das Ergebnis mit Chat.

Tickets#

Lesen Sie Support-Tickets, ändern Sie ihren Status und fügen Sie interne Notizen hinzu. Tickets sind in den Tarifen Evaluation, Support und Automate verfügbar; Free liefert 403 FORBIDDEN. Tickets können nicht über die API erstellt werden: Der Chatbot erstellt sie während einer Konversation.

Endpunkte

Methode und PfadBeschreibungWichtige ParameterMCP-Tool
GET /ticketsTickets auflisten, die neuesten zuerstlimit (Standard 20, max. 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Ein Ticket-get_ticket
PATCH /tickets/{id}Den Status ändernstatus im Bodyupdate_ticket_status
GET /tickets/{id}/notesInterne Notizen, die ältesten zuerst-list_ticket_notes
POST /tickets/{id}/notesEine Notiz hinzufügen; liefert 201content im Bodyadd_ticket_note

GET-Aufrufe nutzen das Lese-Limit (120 pro Minute), PATCH und POST das Schreib-Limit (60 pro Minute); siehe Rate Limits.

Werte

PunktWert
Statusopen, in_progress, resolved, closed
NotizNicht leerer Text, bis zu 5000 Zeichen

Ein ungültiger Status liefert 400 INVALID_REQUEST. Ein Ticket eines anderen Chatbots liefert 404 NOT_FOUND.

Ticketobjekt

{
  "id": "uuid",
  "ticket_number": "TKT-000015",
  "conversation_id": "uuid",
  "email": "visitor@example.com",
  "phone": null,
  "summary": "The visitor asked to speak with a person.",
  "status": "open",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:00:00Z"
}

Beispiel

curl -X PATCH https://www.chatbotty.ai/api/v1/tickets/TICKET_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Webhook-Aktionen#

Verwalten Sie die Webhook-Aktionen des Chatbots: externe APIs oder Automatisierungs-Webhooks (zum Beispiel n8n), die der Chatbot beim Antworten als Tools aufruft. Verfügbar im Tarif Automate (10 Webhooks und 10 Tools pro Chatbot) und in der Testphase Evaluation (5 Webhooks und 5 Tools pro Chatbot). Andere Tarife erhalten 403 FORBIDDEN; das Überschreiten der Limits liefert 403 LIMIT_EXCEEDED. Die Aufrufe verbrauchen das Nachrichtenkontingent nicht.

Endpunkte

Methode und PfadBeschreibungMCP-Tool
GET /webhooksWebhooks und die Nutzung Ihrer Limits auflistenlist_webhook_actions
POST /webhooksEinen Webhook erstellen, optional mit Tools; liefert 201create_webhook_action
GET /webhooks/{id}Ein Webhook mit seinen Toolsget_webhook_action
PATCH /webhooks/{id}Einen Webhook ändernupdate_webhook_action
DELETE /webhooks/{id}Einen Webhook mit seinen Tools löschendelete_webhook_action
POST /webhooks/{id}/toolsEin Tool hinzufügen; liefert 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Ein Tool ändernupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Ein Tool löschendelete_webhook_tool
POST /webhooks/{id}/testDen Webhook so aufrufen, wie es der Chatbot tuttest_webhook_action

Lesezugriffe nutzen das Lese-Limit (120 pro Minute), Änderungen das Schreib-Limit (60), und der Test hat ein eigenes Limit von 20 pro Minute; siehe Rate Limits. Das MCP-Tool get_webhook_guide liefert einen kurzen Leitfaden für KI-Assistenten.

Webhook-Felder

FeldBeschreibung
nameErforderlich, bis zu 100 Zeichen
webhook_urlErforderlich, öffentliche HTTPS-Adresse
http_methodPOST (Standard) oder GET
send_metadataStandard true: Der Aufruf enthält zusätzlich tool_name, args und metadata (chatbot_id, conversation_id, timestamp); false sendet nur die Argumente
timeout_ms1000 bis 30000, Standard 10000
headersBis zu 20 benutzerdefinierte Header
secret_queryBis zu 10 geheime Query-Parameter, zum Beispiel ein API-Schlüssel
toolsTools, die der Chatbot aufrufen darf (siehe unten)

Tool-Felder

FeldBeschreibung
nameKleinbuchstaben, Ziffern und Unterstriche, beginnt mit einem Buchstaben, bis zu 64 Zeichen, pro Chatbot eindeutig; create_support_ticket ist reserviert
descriptionBis zu 500 Zeichen; sagt dem Chatbot, wann er das Tool verwenden soll
parametersBis zu 10 Einträge mit name, type (string, number, boolean), description (bis zu 200 Zeichen), required

Regeln

  • Die Werte von headers und secret_query werden nie zurückgegeben, nur ihre Namen. Ein in webhook_url gefundener Schlüssel wird automatisch nach secret_query verschoben und in warnings gemeldet.
  • Beim Ändern des Endpunkts eines Webhooks müssen alle gespeicherten headers- und secret_query-Schlüssel erneut gesendet werden, sodass Geheimnisse nicht unbemerkt auf einen anderen Server wandern können.
  • Der Chatbot führt pro Antwort eine Runde von Tool-Aufrufen aus. Eine Antwort wird bei 10 KB abgeschnitten, Weiterleitungen werden nicht verfolgt, und interne Adressen werden abgelehnt.

Test

POST /webhooks/{id}/test mit einem optionalen Body { "tool_name": "get_weather", "arguments": { "q": "Prague" } } liefert ok, status, response_time_ms, body_preview (erste 2 KB), truncated und warnings. Stellen Sie nach einem Test dem Chatbot über Chat eine passende Frage und prüfen Sie tools_executed.

Fehler#

Fehlgeschlagene REST-Aufrufe liefern einen HTTP-Status außerhalb von 2xx und diesen Umschlag:

{
  "success": false,
  "error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
  "timestamp": "2026-01-01T10:00:00.000Z"
}

details ist nur bei einigen Fehlern vorhanden. Behandeln Sie Fehler anhand von code; Meldungen können sich ändern.

Fehlercodes

CodeHTTPBedeutung
UNAUTHORIZED401Fehlender, ungültiger oder deaktivierter API-Schlüssel
QUOTA_EXCEEDED403Monatliches Nachrichtenkontingent aufgebraucht (details.quota_info)
FORBIDDEN403Die Funktion ist nicht in Ihrem Tarif enthalten
LIMIT_EXCEEDED403Tarifgrenze für Webhooks oder Tools erreicht (details.resource, used, max)
INVALID_REQUEST400Ungültiger Body oder ungültige Parameter
INVALID_URL400Webhook-URL ist ungültig, nicht HTTPS oder nicht öffentlich
INVALID_FILE400Die Datei fehlt im Upload
FILE_TOO_LARGE400Datei über 10 MB
UNSUPPORTED_FILE_TYPE400Nur .pdf, .docx, .txt, .md werden akzeptiert
CONVERSATION_NOT_FOUND400conversation_id existiert nicht oder gehört zu einem anderen Chatbot
EDIT_FAILED400Zu ersetzender Text nicht gefunden oder mehr als einmal gefunden
NOT_EDITABLE400Nur UTF-8-Dokumente .md und .txt können bearbeitet werden
NOT_FOUND404Dokument, Ticket, Webhook, Tool oder Upload nicht gefunden, oder Chatbot inaktiv
DUPLICATE_FILENAME409Ein Dokument mit diesem Namen existiert (details.existing_document_id)
DUPLICATE_CONTENT409Derselbe Inhalt ist bereits indexiert
REPLACE_IN_PROGRESS409Das Dokument wird ersetzt oder verarbeitet; warten Sie, bis es completed ist
CONFLICT409Tool-Name existiert bereits, oder das Dokument hat sich geändert, seit Sie es gelesen haben
STORAGE_LIMIT_EXCEEDED413Speicherlimit des Chatbots überschritten
RATE_LIMITED429Zu viele Anfragen; siehe Rate Limits
GONE_USE_V1410Der alte Endpunkt /api/chat wurde entfernt; verwenden Sie /api/v1/chat
INTERNAL_ERROR500Unerwarteter Serverfehler

MCP-Fehler

Der MCP-Endpunkt antwortet mit JSON-RPC-Fehlern: 401 bei fehlendem oder ungültigem Token, 429 bei zu vielen Anfragen und 403, wenn der Tarif kein MCP enthält. Schlägt ein Tool fehl, ist das Ergebnis als Fehler gekennzeichnet und enthält den API-Code, zum Beispiel Chatbotty API error [NOT_FOUND] (HTTP 404). Siehe MCP-Connector.

Support

Besteht ein Fehler weiter, schreiben Sie an support@chatbotty.ai und geben Sie den Code, die Uhrzeit und den Endpunkt an.

MCP-Connector#

Der MCP-Connector lässt einen KI-Assistenten wie Claude, n8n oder Cursor mit Ihrem Chatbot arbeiten: mit ihm chatten, seine Wissensdatenbank verwalten, Webhook-Aktionen einrichten und Konversationen, Analysen und Tickets lesen. Ein Connector gehört zu einem Chatbot; um einen anderen Chatbot zu nutzen, fügen Sie einen weiteren Connector hinzu.

Verbindung

PunktWert
Server-URLhttps://www.chatbotty.ai/api/mcp
TransportStreamable HTTP über POST
TarifeAlle Tarife; bei jeder Anfrage geprüft
Limit300 Anfragen pro Minute und Schlüssel (siehe Rate Limits)

Anmeldung oder Schlüssel

MethodeVerwendet vonVorgehen
Anmeldung (OAuth)claude.ai, Claude Desktop, Claude Mobile, Claude CodeDer Client öffnet eine Chatbotty-Seite; Sie melden sich an, wählen den Chatbot und klicken auf Erlauben. Ein Schlüssel wird automatisch erstellt
API-Schlüsseln8n, Cursor, VS Code, andere ClientsSenden Sie den Header Authorization: Bearer YOUR_API_KEY (Authentifizierung)

Ein durch Anmeldung erstellter Schlüssel ist unter API & MCP mit MCP-Connector gekennzeichnet. Löschen Sie ihn dort, um den Assistenten zu trennen. Tickets und Webhook-Tools erscheinen nur, wenn Ihr Tarif sie enthält. Die Einrichtungsschritte finden Sie unter MCP-Clients.

Tools

BereichTools
Chatbot und Chatget_chatbot_info, send_message
Dokumentelist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Wissenslückenlist_knowledge_gaps
Konversationenlist_conversations, get_conversation, get_conversation_messages
Analysenget_analytics_summary, get_analytics_timeseries, get_top_queries
Tickets (Tarife mit Tickets)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Webhook-Aktionen (Tarife mit Webhook-Aktionen)get_webhook_guide, list_webhook_actions, get_webhook_action, create_webhook_action, update_webhook_action, test_webhook_action, delete_webhook_action, add_webhook_tool, update_webhook_tool, delete_webhook_tool

Jedes Tool funktioniert wie der entsprechende REST-Endpunkt, der in den obigen Abschnitten beschrieben ist, und hat dieselben Limits und Fehler.

Gut zu wissen

  • send_message spricht wie ein Besucher mit dem Chatbot und verbraucht das monatliche Nachrichtenkontingent. test_webhook_action nicht.
  • list_knowledge_gaps listet Fragen auf, die der Chatbot nicht beantworten konnte, und benötigt einen Zeitraum; nutzen Sie es, um herauszufinden, was in die Wissensdatenbank aufgenommen werden sollte.
  • Ein Client speichert Tool-Beschreibungen möglicherweise im Cache. Wirken Tools veraltet, entfernen Sie den Connector und fügen Sie ihn erneut hinzu.

MCP-Clients#

So verbinden Sie gängige Clients mit https://www.chatbotty.ai/api/mcp. Bei Clients, die einen Schlüssel senden, erstellen Sie ihn zuerst wie unter Authentifizierung beschrieben. Hintergrund: MCP-Connector.

Claude (claude.ai, Claude Desktop, Mobile)

  1. Öffnen Sie Settings, dann Connectors, und fügen Sie einen benutzerdefinierten Connector hinzu.
  2. Fügen Sie die Server-URL ein und klicken Sie auf Connect.
  3. Melden Sie sich bei Chatbotty an, wählen Sie den Chatbot und klicken Sie auf Erlauben.

Es wird kein API-Schlüssel benötigt. Der Connector funktioniert danach auch in der mobilen Claude-App.

Claude Code

Über den Browser anmelden:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp

Oder einen API-Schlüssel verwenden:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Warnt die Anmeldeseite, dass die App auf Ihrem eigenen Computer läuft, erlauben Sie den Zugriff nur, wenn Sie die Verbindung selbst gestartet haben.

n8n

  1. Fügen Sie den Node MCP Client Tool hinzu.
  2. Endpoint: die Server-URL.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth mit Ihrem API-Schlüssel.

Cursor, VS Code und andere Clients

Fügen Sie einen Remote-MCP-Server mit der Server-URL und dem Header Authorization: Bearer YOUR_API_KEY hinzu. In Cursor zum Beispiel:

{
  "mcpServers": {
    "chatbotty": {
      "url": "https://www.chatbotty.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Fehlerbehebung

ProblemPrüfen
401Der Schlüssel ist falsch, deaktiviert oder gelöscht
Tickets oder Webhook-Tools fehlenIhr Tarif enthält sie nicht
Ein manueller Client erhält 406Der Client muss Accept: application/json, text/event-stream senden

Beispiele#

Beispiele zum Kopieren für die häufigsten Aufgaben. Ersetzen Sie YOUR_API_KEY durch einen Schlüssel unter API & MCP und https://www.chatbotty.ai durch die Basis-URL. Siehe Authentifizierung.

Chatbot und Kontingent prüfen

curl https://www.chatbotty.ai/api/v1/chatbot \
  -H "Authorization: Bearer YOUR_API_KEY"

Eine Frage stellen und die Konversation fortsetzen

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

Entnehmen Sie conversation_id der Antwort und senden Sie sie mit der nächsten Nachricht:

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "And on Sunday?", "conversation_id": "CONVERSATION_ID"}'

Ein Dokument hochladen

curl -X POST https://www.chatbotty.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./faq.md"

Prüfen Sie dann den Status, bis er completed ist:

curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Unbeantwortete Fragen finden

curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Konversationen auflisten, die ein Wort enthalten

curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fehler behandeln

{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 60 requests per minute per API key." }, "timestamp": "2026-01-01T10:00:00.000Z" }

Verzweigen Sie anhand von error.code und siehe Fehler. Zu den Limits siehe Rate Limits. Fragen: support@chatbotty.ai.