Überblick

Quickchat AI stellt eine REST-API für den programmatischen Zugriff auf die Konfiguration Ihres KI-Agenten, die Wissensdatenbank, Konversationen, AI Actions und mehr bereit.

Authentifizierung

Alle API-Endpunkte verwenden Bearer-Token-Authentifizierung. Fügen Sie Ihren API-Token im Authorization-Header jeder Anfrage ein:

Authorization: Bearer <API_TOKEN>

Tokens werden im Quickchat Dashboard unter External Apps > API erstellt. Jeder Token ist ein JWT, das Ihre scenario_id enthält, sodass kein zusätzlicher Identifier-Header erforderlich ist.

• Token-Gültigkeit: 52 Wochen ab Erstellung
• Tokens können jederzeit über das Dashboard widerrufen werden
• Jeder Token ist auf einen einzelnen KI-Agenten (Szenario) beschränkt
• Das Erstellen von Tokens erfordert den Business-Tarif oder höher; in niedrigeren Tarifen ist die Option deaktiviert und der Endpunkt liefert 402 Payment Required

Hinweis

Der Echtzeit-Chat-Endpunkt (POST https://app.quickchat.ai/chat) akzeptiert denselben Bearer-Token wie der Rest dieser API, liegt aber außerhalb des Basis-Pfads /v1/api/ und erfordert scenario_id im Request-Body. Die vollständige Referenz finden Sie auf der Seite Chat.

Token-Scopes

API-Tokens werden mit einem von zwei Scopes erstellt:

Scope	Access Level	Description
read_all	Read-only	Kann alle Ressourcen lesen, aber nicht erstellen, aktualisieren oder löschen
write_all	Read + Write	Vollzugriff auf alle Endpunkte, einschließlich Schreiboperationen

• Tokens wird beim Erstellen im Dashboard unter External Apps > API ein Scope zugewiesen
• Der Scope write_all umfasst automatisch alle read_all-Berechtigungen
• Die Verwendung eines read_all-Tokens auf einem Schreib-Endpunkt liefert 403 mit "Insufficient token scope. Required: write_all"

Tipp

Verwenden Sie read_all-Tokens für Monitoring, Analytics und lesende Integrationen. Verwenden Sie write_all-Tokens nur, wenn Ihre Integration Ressourcen erstellen oder ändern muss.

Scope-Anforderungen nach Endpunktgruppe:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

Basis-URL

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Rate-Limits

Rate-Limits werden pro Token und pro Endpunkt angewendet.

Tier	Limit	Applies To
READ	120 Anfragen/Min	GET- und List-Operationen
WRITE	60 Anfragen/Min	POST, PATCH, PUT, DELETE
HEAVY	20 Anfragen/Min	Datei-Uploads, Importe, Scraping

Wenn ein Rate-Limit überschritten wird, gibt die API HTTP 429 Too Many Requests zurück.

Webhooks

Quickchat AI sendet keine ausgehenden Webhooks. Es gibt keine Möglichkeit, ein Ereignis zu abonnieren und sich von uns per POST an Ihren Endpunkt benachrichtigen zu lassen, wenn eine Nachricht eintrifft, eine Konversation übergeben wird oder eine Konversation geschlossen wird.

Um Daten in dem Moment herauszubekommen, in dem etwas passiert, nutzen Sie stattdessen eine dieser Optionen:

• KI‑Aktionen: Die KI ruft mitten in der Konversation Ihre API auf. Das kommt einem Webhook am nächsten und funktioniert per Push, nicht per Polling: Ihr Endpunkt wird angesprochen, während die Konversation läuft. Ausgelöst wird die Aktion, wenn die KI entscheidet, dass sie zutrifft. Sie eignet sich damit besser für „mein System über diesen Lead informieren“ als für „mein System über jede Nachricht informieren“.
• Google Sheets: hängt eine Zeile pro Ereignis an, ohne dass Sie einen Endpunkt bauen müssen.
• Polling der Conversations API: für einen vollständigen Datensatz. Beachten Sie dabei das oben genannte READ-Limit.

Der API-Zugriff erfordert den Business-Tarif, siehe Tarife & Limits.

Paginierung

Listen-Endpunkte unterstützen Paginierung über Query-Parameter:

Parameter	Description
limit integer	Anzahl der Elemente pro Seite
offset integer	Anzahl der zu überspringenden Elemente

Paginierte Antworten folgen dieser Struktur:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Fehlerbehandlung

Alle Fehler werden als JSON im folgenden Format zurückgegeben:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Ungültige Eingabe oder fehlende Pflichtfelder
401	PERMISSION_DENIED	Ungültiger, abgelaufener oder widerrufener Token
402	PAYMENT_REQUIRED	Aktives Abonnement erforderlich
403	PERMISSION_DENIED	Dem Token fehlt der für diese Operation erforderliche Scope
404	NOT_FOUND	Ressource nicht gefunden
409	CONFLICT	Konflikt bei der Operation (z. B. gleichzeitige Änderung)
422	VALIDATION_ERROR	Request-Body hat die Schema-Validierung nicht bestanden
429	TOO_MANY_REQUESTS	Rate-Limit überschritten
500	UNKNOWN	Interner Serverfehler
503	SERVICE_UNAVAILABLE	Vorübergehende Nichtverfügbarkeit

---