API (Legacy)

Hinweis zur Einstellung

Diese Seite dokumentiert die veraltete Chat-API mit API-Key-Authentifizierung. Fuer die neue Bearer-Token-API mit Zugriff auf Wissensbasis-, Konversations- und KI-Aktions-Endpunkte siehe API.

In diesem Leitfaden erlaeutern wir die Schritte, die zur Integration Ihres individuellen Quickchat-KI-Assistenten in Ihr Produkt ueber einen API-Endpunkt erforderlich sind.

Authentifizierung

Fuegen Sie in jeder Anfrage Ihren API Key und die scenario_id hinzu.

Um Ihren API-Schluessel zu erhalten, upgraden Sie Ihr Abonnement mit API-Zugang.

Chat

Neue Konversation / neuen Nutzerverlauf initialisieren

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "text": "Hello!"
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Die obige Anfrage liefert JSON in dieser Struktur:

{
  "ord_number": 2,
  "conv_id": "abcd1234",
  "reply": "Hey there! 🙂"
}

conv_id ist ein optionaler Parameter. Eine Anfrage ohne conv_id startet eine neue Konversation, und die neu generierte conv_id wird zurueckgegeben.

Verknuepfen Sie conv_id mit Ihrem jeweiligen Nutzer, um den Konversationskontext ueber die Zeit und mehrere Interaktionen hinweg beizubehalten.

Dieser Endpunkt fuehrt einen einzelnen Gespraechsaustausch durch.

HTTP-Anfrage

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

Query Parameters

Parameter	Type	Description
api_key	string	Erstellen Sie ein Konto und abonnieren Sie, um Ihren API-Schluessel zu erhalten
scenario_id	Text	ID Ihrer Quickchat-API-Implementierung
text	string	Eingabenachricht des Nutzers

Nachricht an den KI-Assistenten senden

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Die obige Anfrage liefert JSON in dieser Struktur:

{
  "ord_number": 236,
  "reply": "Hey, great to hear from you again! 😉"
}

HTTP-Anfrage

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

Query Parameters

Parameter	Type	Description
api_key	string	Erstellen Sie ein Konto und abonnieren Sie, um Ihren API-Schluessel zu erhalten
scenario_id	string	ID Ihrer Quickchat-API-Implementierung
conv_id	string (Optional)	Identifiziert eine bestimmte Konversation/einen Nutzer
text	string	Eingabenachricht des Nutzers
message_context	string (Optional)	Zusaetzlicher clientseitiger Pro-Nachricht-Kontext, der zusammen mit der Nachricht an die KI uebergeben wird
client_metadata	dict (Optional)	Zum Beispiel {userId: 12, website: mywebsite.com}. Maximal 5 Schluessel gleichzeitig. Diese Parameter werden jeder neuen Nachricht zugewiesen und als Datenspalten im Konversationsexport im Posteingang angezeigt

Nachrichten mit benutzerdefiniertem Kontext und Metadaten

Wie in der obigen Parametertabelle beschrieben, erlaubt der Endpunkt https://chat.quickchat.ai/chat zwei optionale Parameter: message_context und client_metadata.

Client-Metadaten sind benutzerdefinierte Attribute, die jeder neuen Nachricht zugewiesen werden und als Datenspalten im Konversationsexport im Posteingang angezeigt werden. Sie koennen auch ueber das Widget benutzerdefinierte Attribute zu den Nachrichten hinzufuegen, mit demselben Effekt.

Der Nachrichtenkontext ermoeglicht es Ihnen, beispielsweise nutzerspezifischen Kontext zu jeder Nachricht mitzugeben, um jeder Konversation eine persoenlichere Note zu verleihen.

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
  "message_context": "The users name is John.",
  "client_metadata": {userId: 12, website: mywebsite.com}
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'userId': 12, 'website': 'mywebsite.com'}
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Wissensbasis-Tag-Filter ueber die API setzen

In der Quickchat AI App haben Sie die Moeglichkeit, jedem Artikel Tags hinzuzufuegen. Diese koennen verwendet werden, um die Wissensbasis zu filtern, sodass die KI nur auf Basis einer Teilmenge von Artikeln aus der Wissensbasis antwortet. Bitte beachten Sie, dass dieses Feature bisher nur ueber die API unterstuetzt wird.

Um nach Wissensbasis-Themen (Tags) zu filtern, fuegen Sie kb_topic zu Ihren client_metadata in den API-Aufrufen hinzu. Stellen Sie dabei sicher, dass der Schluessel kb_topic bei jedem API-Aufruf vorhanden ist, einschliesslich der Initialisierung der Konversation. Der Wert von kb_topic kann sich zwischen API-Aufrufen aendern, aber der Parameter selbst muss waehrend der gesamten Konversation konstant vorhanden sein, um von unserem System beruecksichtigt zu werden.

Das folgende Beispiel zeigt, wie Sie kb_topic zu client_metadata hinzufuegen. Im Beispiel werden alle Artikel mit dem Tag your-topic oder ohne Tag fuer den Wissenspool der Antwort ausgewaehlt.

json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'kb_topic': 'your-topic'}
  }

Fehler

Nachfolgend finden Sie die Fehlercodes, die von der API zurueckgegeben werden koennen, zusammen mit ihrer Beschreibung und moeglichen Loesungen.

Code	Description	Action
400	Die folgenden Parameter muessen angegeben werden: api_key, scenario_id, text	Bitte stellen Sie sicher, dass alle erforderlichen Parameter angegeben sind.
400	conv_id abcd1234 existiert nicht	Bitte stellen Sie sicher, dass die verwendete conv_id korrekt ist.
400	Das Limit fuer den Nachrichtenkontext betraegt 1000 Zeichen.	Bitte kuerzen Sie den Nachrichtenkontext auf 1000 Zeichen einschliesslich Leerzeichen.
401	Nicht autorisiert	Bitte stellen Sie sicher, dass api_key und scenario_id korrekt sind (siehe Integrations - API in der App).
500	Interner Serverfehler	Es liegt ein Problem auf unserer Seite vor. Bitte kontaktieren Sie den Support.
503	Dienst nicht verfuegbar	Unsere Server sind ueberlastet oder voruebergehend wegen Wartungsarbeiten nicht verfuegbar. Falls das Problem weiterhin besteht, kontaktieren Sie bitte den Support.