Ü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.

Die verfügbaren Alternativen erfüllen unterschiedliche Zwecke:

• AI-Aktionen rufen Ihre API während einer Konversation auf. API-Aktionen bieten die Modi AI entscheidet, Vor der ersten Antwort und Wenn Metadaten übereinstimmen. Die automatischen Modi versuchen unter den jeweils dokumentierten Bedingungen einmal pro Konversation einen Aufruf. Sie sind keine Abonnements für jede Nachricht oder Übergabe. Nutzen Sie sie beispielsweise, um einen Lead zu erfassen oder Ihr System zu benachrichtigen, sobald die benötigten Daten verfügbar sind.
• Google Sheets fügt eine Zeile hinzu, wenn die zugehörige Aktion ausgeführt wird. Es erfasst nicht automatisch jede Nachricht oder Übergabe.
• Polling der Conversations API ruft gespeicherte Konversationen und deren Ereignisse ab, einschließlich Nachrichten und gegebenenfalls aufgezeichneter Übergabemarkierungen. Beachten Sie die Paginierung und das oben genannte READ-Rate-Limit. Polling führt zu Verzögerungen. Beim Vergleich des Konversationsstatus zwischen Abfragen können zwischenzeitliche Änderungen übersehen werden. Gehen Sie nicht davon aus, dass dies einen vollständigen Verlauf aller Übergaben oder Zuweisungsänderungen liefert.

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

---