Chat

Chat

Der Echtzeit-Chat-Endpunkt sendet eine Besuchernachricht an Ihren KI-Agenten und liefert die KI-Antwort in einem einzigen Round-Trip zurück. Das ist der Endpunkt, den Sie benötigen, wenn Sie eine eigene Chat-UI auf Basis von Quickchat AI bauen.

Er unterscheidet sich in zwei Punkten von den anderen Endpunkten: Er liegt unter app.quickchat.ai/chat, außerhalb der Basis-Pfade /v1/api/ und /v1/api_core/, und er liest scenario_id aus dem Request-Body statt aus dem Token. Er verwendet dieselbe Bearer-Token-Authentifizierung wie der Rest dieser API.

Hinweis

Senden Sie jede Anfrage an https://app.quickchat.ai/chat. Die scenario_id im Body muss mit dem KI-Agenten übereinstimmen, an den Ihr Bearer-Token gebunden ist.

Nachricht senden

POST https://app.quickchat.ai/chat

Request-Body

Parameter	Description
scenario_id string, required	ID Ihres KI-Agenten. Muss mit der an den Bearer-Token gebundenen scenario_id übereinstimmen
text string, required	Eingabenachricht des Nutzers
conv_id string	Konversations-ID. Bei der ersten Anfrage weglassen, um eine neue Konversation zu starten, dann die zurückgegebene conv_id bei nachfolgenden Anfragen zurücksenden, um sie fortzusetzen
client_metadata object	Benutzerdefinierte Schlüssel-Wert-Paare (wir empfehlen höchstens 5 Schlüssel), die jeder Nachricht angehängt werden. Werden im Konversationsexport in der Inbox als Datenspalten angezeigt

Eine Anfrage ohne conv_id startet eine neue Konversation, und die generierte conv_id wird in der Antwort zurückgegeben. Speichern Sie diese conv_id und senden Sie sie bei späteren Anfragen zurück, um den Konversationskontext über mehrere Nutzerinteraktionen hinweg aufrechtzuerhalten.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Antwort 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Field	Description
conv_id string	Konversations-Identifier. Wird immer zurückgegeben. Senden Sie ihn im Body-Feld conv_id zurück, um die Konversation fortzusetzen
reply string	Antwort des KI-Agenten. Kann HTML wie <br>-Zeilenumbrüche enthalten
ord_number integer	Fortlaufende Nachrichtennummer innerhalb der Konversation
src integer	Interner Quellindikator. API-Clients können dieses Feld ignorieren

Um eine bestehende Konversation fortzusetzen, senden Sie die erhaltene conv_id zurück:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Client Metadata

Der Chat-Endpunkt akzeptiert einen optionalen Parameter client_metadata: benutzerdefinierte Attribute, die jeder neuen Nachricht zugewiesen und im Konversationsexport in der Inbox als Datenspalten angezeigt werden. Sie können dieselben Attribute auch über das Widget anhängen. Wir empfehlen, jeweils höchstens 5 Schlüssel zu senden, zum Beispiel {"userId": 12, "website": "mywebsite.com"}. Dies ist eine Empfehlung, kein von der API erzwungenes Limit.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Filterung der Wissensdatenbank nach Tags

Sie können Tags zu Artikeln der Wissensdatenbank hinzufügen und damit einschränken, auf welche Artikel die KI zurückgreift, sodass sie nur auf Basis einer Teilmenge der Wissensdatenbank antwortet. Diese Filterung wird derzeit nur über die API unterstützt.

Um nach Tag zu filtern, fügen Sie client_metadata einen Schlüssel kb_topic hinzu. Der Schlüssel kb_topic muss in jeder Anfrage der Konversation vorhanden sein, einschließlich der Anfrage, die sie startet. Sein Wert kann sich zwischen den Anfragen ändern, der Schlüssel selbst muss aber während der gesamten Konversation vorhanden sein, damit der Filter greift.

Im folgenden Beispiel wird jeder mit your-topic getaggte Artikel oder jeder Artikel ohne Tag in den Kandidatenpool des Wissens für die Antwort aufgenommen.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Fehler

Der Chat-Endpunkt gibt eine Klartext-Fehlermeldung mit einem passenden HTTP-Statuscode zurück.

Status	Description	Action
400	Fehlende scenario_id oder keine Anmeldedaten angegeben	Fügen Sie scenario_id in den Body und einen gültigen Authorization: Bearer <API_TOKEN>-Header ein
400	Ungültige conv_id (Conversation conv_id <id> is not valid.)	Lassen Sie conv_id weg, um eine neue Konversation zu starten, oder senden Sie eine von einer vorherigen Antwort zurückgegebene conv_id
401	Ungültige Anmeldedaten (Unauthorized.)	Prüfen Sie, ob Ihr Bearer-Token oder API-Key für diese scenario_id gültig ist
404	Unbekannte scenario_id (No implementation found for scenario_id <id>)	Überprüfen Sie die scenario_id und ob Ihr Bearer-Token daran gebunden ist
500	Interner Serverfehler	Ein Problem auf unserer Seite. Bitte kontaktieren Sie den Support
503	Service nicht verfügbar	Die Server sind vorübergehend überlastet oder in Wartung. Wenn das Problem weiterhin besteht, kontaktieren Sie bitte den Support