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
| Punkt | Wert |
|---|---|
| REST-Basis-URL | https://www.chatbotty.ai/api/v1 |
| MCP-Server-URL | https://www.chatbotty.ai/api/mcp |
| Format | JSON über HTTPS |
| Authentifizierung | Authorization: Bearer YOUR_API_KEY |
| Geltungsbereich eines Schlüssels | Ein 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.
| Funktion | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, Dokumente, Konversationen, Analysen | Ja | Ja | Ja | Ja |
| Tickets | Nein | Ja | Ja | Ja |
| Webhook-Aktionen | Nein | Ja | Nein | Ja |
| Dokumentimport von einer Web-URL | Nein | Ja | Ja | Ja |
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 /chatoder das MCP-Toolsend_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 mitGET /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_FOUNDablehnt).
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
| Punkt | Wert |
|---|---|
| Format | Eine zufällige hexadezimale Zeichenfolge mit 64 Zeichen |
| Geltungsbereich | Ein Chatbot pro Schlüssel |
| Limit | Bis zu 50 Schlüssel pro Chatbot (inaktive Schlüssel zählen mit) |
| Speicherung | Nur 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
- Öffnen Sie API & MCP in der Seitenleiste.
- 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.
- 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.
| Aktion | Wirkung |
|---|---|
| Deaktivieren | Der Schlüssel funktioniert sofort nicht mehr; Aktivieren schaltet ihn wieder ein |
| Löschen | Der 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
| Situation | Antwort |
|---|---|
| Header fehlt oder ist fehlerhaft | 401 UNAUTHORIZED „Missing or invalid Authorization header“ |
| Unbekannter oder deaktivierter Schlüssel | 401 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
| Klasse | Endpunkte | Limit pro Minute |
|---|---|---|
| Chat | POST /chat | 60 |
| Lesen | Alle anderen GET-Endpunkte außer Analysen (einschließlich GET /chatbot) | 120 |
| Schreiben | POST-, PATCH-, DELETE-Endpunkte | 60 |
| Analysen | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Webhook-Test | POST /webhooks/{id}/test | 20 |
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
| Punkt | Wert |
|---|---|
| Methode und Pfad | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parameter | Keine |
| Rate Limit | Klasse Lesen (siehe Rate Limits) |
| Kontingent | Nicht verbraucht |
| MCP-Tool | get_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
planundmessage_quotagehören zum Kontoinhaber; das Kontingent wird von allen Chatbots des Kontos geteilt.featureszeigt, welche tarifabhängigen Funktionen dieser Schlüssel nutzen kann.handoff_contactist der Kontakt, den der Chatbot nennt, wenn er die Antwort nicht kennt (hier schreibgeschützt;null, wenn nicht gesetzt).last_updated_atist 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
| Punkt | Wert |
|---|---|
| Methode und Pfad | POST https://www.chatbotty.ai/api/v1/chat |
| Rate Limit | Klasse Chat: 60 pro Minute |
| Kontingent | Eine Nachricht pro Aufruf; über dem Kontingent liefert der Aufruf 403 QUOTA_EXCEEDED |
| MCP-Tool | send_message |
Anfragekörper
| Feld | Erforderlich | Beschreibung |
|---|---|---|
message | Ja | Die Frage des Besuchers (nicht leerer Text) |
conversation_id | Nein | Setzt eine bestehende Konversation fort; weglassen, um eine neue zu starten |
options | Nein | Optionales 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 Pfad | Beschreibung | Wichtige Parameter | MCP-Tool |
|---|---|---|---|
GET /documents | Dokumente auflisten | limit (Standard 20, max. 100), offset, status | list_documents |
POST /documents | Ein Dokument hochladen; liefert 202 | Siehe unten | upload_document |
POST /documents/upload-url | Eine signierte URL für eine große oder lokale Datei abrufen | filename | create_upload_url |
GET /documents/{id} | Status und Details eines Dokuments | - | get_document |
DELETE /documents/{id} | Ein Dokument löschen | - | delete_document |
GET /documents/{id}/content | Den Text seitenweise lesen | offset, limit (Standard 20000, max. 50000) | read_document |
PATCH /documents/{id}/content | Ein .md- oder .txt-Dokument bearbeiten | edits, append, expected_hash | edit_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.
| Feld | Beschreibung |
|---|---|
file | Die Datei (nur multipart) |
content | Text eines .md- oder .txt-Dokuments (JSON; filename erforderlich) |
content_base64 | Binä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_id | ID aus POST /documents/upload-url, nachdem Sie die Datei hochgeladen haben |
filename | Dateiname mit Erweiterung |
description | Optionale Beschreibung |
replace_existing | Standard 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
POST /documents/upload-urlmit{ "filename": "price-list.pdf" }. Die Antwort enthältupload_id,upload_urlund Header; die URL ist 2 Stunden gültig und funktioniert einmal.- Senden Sie die Rohdatei per
PUTanupload_url. POST /documentsmit{ "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}/contentsendet nur die Änderung:edits(Liste ausold_textundnew_text, jederold_textmuss genau einmal vorkommen, bis zu 100) und/oderappend(text, optionalafter_heading).expected_hash(ausGET .../content) schützt davor, eine neuere Version zu überschreiben (409 CONFLICT).- Nur UTF-8-Dokumente
.mdund.txtkönnen bearbeitet werden (sonst400 NOT_EDITABLE). - Jede Bearbeitung oder Ersetzung erzeugt eine neue
document_id; die alte Version antwortet weiter, bis die neuecompletedist. - 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 Pfad | Beschreibung | Wichtige Parameter | MCP-Tool |
|---|---|---|---|
GET /conversations | Konversationen auflisten | Siehe unten | list_conversations |
GET /conversations/{id} | Eine Konversation | - | get_conversation |
GET /conversations/{id}/messages | Nachrichten in chronologischer Reihenfolge | limit (Standard 50, max. 200), offset | get_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
| Parameter | Beschreibung |
|---|---|
limit, offset | Seitenaufteilung (Standard 20, max. 100) |
status | active, completed oder ticket_created |
source | widget oder api |
from, to | ISO-8601-Daten; filtern nach dem Beginn der Konversation |
quality | Konversationen mit mindestens einer Frage dieser Art: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Volltextsuche 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 Pfad | Beschreibung | MCP-Tool |
|---|---|---|
GET /analytics/summary | Summen für den Zeitraum | get_analytics_summary |
GET /analytics/timeseries | Anzahlen pro Stunde, Tag oder Woche | get_analytics_timeseries |
GET /analytics/top-queries | Häufigste Fragen | get_top_queries, list_knowledge_gaps |
Alle drei nutzen das Analysen-Limit von 60 Anfragen pro Minute (siehe Rate Limits).
Gemeinsame Parameter
| Parameter | Beschreibung |
|---|---|
period | today (Standard), week, month oder quarter, ausgewertet in der Zeitzone des Chatbots |
from, to | ISO-8601-Daten; sie ersetzen period; der Bereich beträgt höchstens 366 Tage |
source | widget oder api |
Zusätzliche Parameter
| Endpunkt | Parameter | Beschreibung |
|---|---|---|
timeseries | granularity | auto (Standard), hour, day oder week; hour mit quarter wird abgelehnt |
top-queries | limit, offset | Seitenaufteilung (Standard 20, max. 100) |
top-queries | quality | answered, 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 Pfad | Beschreibung | Wichtige Parameter | MCP-Tool |
|---|---|---|---|
GET /tickets | Tickets auflisten, die neuesten zuerst | limit (Standard 20, max. 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Ein Ticket | - | get_ticket |
PATCH /tickets/{id} | Den Status ändern | status im Body | update_ticket_status |
GET /tickets/{id}/notes | Interne Notizen, die ältesten zuerst | - | list_ticket_notes |
POST /tickets/{id}/notes | Eine Notiz hinzufügen; liefert 201 | content im Body | add_ticket_note |
GET-Aufrufe nutzen das Lese-Limit (120 pro Minute), PATCH und POST das Schreib-Limit (60 pro Minute); siehe Rate Limits.
Werte
| Punkt | Wert |
|---|---|
| Status | open, in_progress, resolved, closed |
| Notiz | Nicht 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 Pfad | Beschreibung | MCP-Tool |
|---|---|---|
GET /webhooks | Webhooks und die Nutzung Ihrer Limits auflisten | list_webhook_actions |
POST /webhooks | Einen Webhook erstellen, optional mit Tools; liefert 201 | create_webhook_action |
GET /webhooks/{id} | Ein Webhook mit seinen Tools | get_webhook_action |
PATCH /webhooks/{id} | Einen Webhook ändern | update_webhook_action |
DELETE /webhooks/{id} | Einen Webhook mit seinen Tools löschen | delete_webhook_action |
POST /webhooks/{id}/tools | Ein Tool hinzufügen; liefert 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Ein Tool ändern | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Ein Tool löschen | delete_webhook_tool |
POST /webhooks/{id}/test | Den Webhook so aufrufen, wie es der Chatbot tut | test_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
| Feld | Beschreibung |
|---|---|
name | Erforderlich, bis zu 100 Zeichen |
webhook_url | Erforderlich, öffentliche HTTPS-Adresse |
http_method | POST (Standard) oder GET |
send_metadata | Standard true: Der Aufruf enthält zusätzlich tool_name, args und metadata (chatbot_id, conversation_id, timestamp); false sendet nur die Argumente |
timeout_ms | 1000 bis 30000, Standard 10000 |
headers | Bis zu 20 benutzerdefinierte Header |
secret_query | Bis zu 10 geheime Query-Parameter, zum Beispiel ein API-Schlüssel |
tools | Tools, die der Chatbot aufrufen darf (siehe unten) |
Tool-Felder
| Feld | Beschreibung |
|---|---|
name | Kleinbuchstaben, Ziffern und Unterstriche, beginnt mit einem Buchstaben, bis zu 64 Zeichen, pro Chatbot eindeutig; create_support_ticket ist reserviert |
description | Bis zu 500 Zeichen; sagt dem Chatbot, wann er das Tool verwenden soll |
parameters | Bis zu 10 Einträge mit name, type (string, number, boolean), description (bis zu 200 Zeichen), required |
Regeln
- Die Werte von
headersundsecret_querywerden nie zurückgegeben, nur ihre Namen. Ein inwebhook_urlgefundener Schlüssel wird automatisch nachsecret_queryverschoben und inwarningsgemeldet. - Beim Ändern des Endpunkts eines Webhooks müssen alle gespeicherten
headers- undsecret_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
| Code | HTTP | Bedeutung |
|---|---|---|
UNAUTHORIZED | 401 | Fehlender, ungültiger oder deaktivierter API-Schlüssel |
QUOTA_EXCEEDED | 403 | Monatliches Nachrichtenkontingent aufgebraucht (details.quota_info) |
FORBIDDEN | 403 | Die Funktion ist nicht in Ihrem Tarif enthalten |
LIMIT_EXCEEDED | 403 | Tarifgrenze für Webhooks oder Tools erreicht (details.resource, used, max) |
INVALID_REQUEST | 400 | Ungültiger Body oder ungültige Parameter |
INVALID_URL | 400 | Webhook-URL ist ungültig, nicht HTTPS oder nicht öffentlich |
INVALID_FILE | 400 | Die Datei fehlt im Upload |
FILE_TOO_LARGE | 400 | Datei über 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Nur .pdf, .docx, .txt, .md werden akzeptiert |
CONVERSATION_NOT_FOUND | 400 | conversation_id existiert nicht oder gehört zu einem anderen Chatbot |
EDIT_FAILED | 400 | Zu ersetzender Text nicht gefunden oder mehr als einmal gefunden |
NOT_EDITABLE | 400 | Nur UTF-8-Dokumente .md und .txt können bearbeitet werden |
NOT_FOUND | 404 | Dokument, Ticket, Webhook, Tool oder Upload nicht gefunden, oder Chatbot inaktiv |
DUPLICATE_FILENAME | 409 | Ein Dokument mit diesem Namen existiert (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | Derselbe Inhalt ist bereits indexiert |
REPLACE_IN_PROGRESS | 409 | Das Dokument wird ersetzt oder verarbeitet; warten Sie, bis es completed ist |
CONFLICT | 409 | Tool-Name existiert bereits, oder das Dokument hat sich geändert, seit Sie es gelesen haben |
STORAGE_LIMIT_EXCEEDED | 413 | Speicherlimit des Chatbots überschritten |
RATE_LIMITED | 429 | Zu viele Anfragen; siehe Rate Limits |
GONE_USE_V1 | 410 | Der alte Endpunkt /api/chat wurde entfernt; verwenden Sie /api/v1/chat |
INTERNAL_ERROR | 500 | Unerwarteter 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
| Punkt | Wert |
|---|---|
| Server-URL | https://www.chatbotty.ai/api/mcp |
| Transport | Streamable HTTP über POST |
| Tarife | Alle Tarife; bei jeder Anfrage geprüft |
| Limit | 300 Anfragen pro Minute und Schlüssel (siehe Rate Limits) |
Anmeldung oder Schlüssel
| Methode | Verwendet von | Vorgehen |
|---|---|---|
| Anmeldung (OAuth) | claude.ai, Claude Desktop, Claude Mobile, Claude Code | Der 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üssel | n8n, Cursor, VS Code, andere Clients | Senden 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
| Bereich | Tools |
|---|---|
| Chatbot und Chat | get_chatbot_info, send_message |
| Dokumente | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Wissenslücken | list_knowledge_gaps |
| Konversationen | list_conversations, get_conversation, get_conversation_messages |
| Analysen | get_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_messagespricht wie ein Besucher mit dem Chatbot und verbraucht das monatliche Nachrichtenkontingent.test_webhook_actionnicht.list_knowledge_gapslistet 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)
- Öffnen Sie Settings, dann Connectors, und fügen Sie einen benutzerdefinierten Connector hinzu.
- Fügen Sie die Server-URL ein und klicken Sie auf Connect.
- 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
- Fügen Sie den Node MCP Client Tool hinzu.
- Endpoint: die Server-URL.
- Server Transport: HTTP Streamable.
- 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
| Problem | Prüfen |
|---|---|
401 | Der Schlüssel ist falsch, deaktiviert oder gelöscht |
| Tickets oder Webhook-Tools fehlen | Ihr Tarif enthält sie nicht |
Ein manueller Client erhält 406 | Der 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.