Conversation Metadata

Mit Conversation Metadata können Sie benutzerdefinierte Schlüssel-Wert-Daten an Konversationen anhängen und so eine leistungsstarke Brücke zwischen Ihren Systemen und Ihrem KI-Agenten schlagen. Metadaten fließen durch Ihren gesamten Quickchat-Workflow:

• Über die API einspeisen — Verwenden Sie diese Endpunkte, um Metadaten programmatisch an jede beliebige Konversation anzuhängen (z. B. aus Ihrem CRM, Helpdesk oder Backend)
• Über Widget/Embed einspeisen — Übergeben Sie Metadaten als Initialisierungsparameter beim Laden des Widgets oder injizieren Sie sie während einer aktiven Konversation dynamisch über das JavaScript-SDK
• Sichtbar im Dashboard: Benutzerdefinierte Metadaten erscheinen in den Konversationsdetails des Posteingangs. Interne Schlüssel werden herausgefiltert; erfasste Kontaktdaten und der Aktionsspeicher werden separat dargestellt
• In Exporten enthalten — Metadaten werden einbezogen, wenn Sie Konversationen aus dem Dashboard exportieren, und stehen so für Offline-Analysen zur Verfügung
• In AI Actions verwendet — Metadaten-Werte können direkt als {{metadata_<key>}}-Platzhalter in AI Actions injiziert werden. Die vollständige Referenz der verfügbaren Platzhalter finden Sie unter AI Action Variables
• Für den AI Agent verfügbar, sofern zulässig: Der Modellkontext enthält eine gefilterte Teilmenge der Metadaten. Das Speichern eines Schlüssels garantiert nicht, dass das Modell ihn erhält oder erwähnt

Verwenden Sie Metadaten für Kundenreferenzen, Kontokontext, Analysen und Eingabewerte für Aktionen. Speicherung, Anzeige im Posteingang, Ersetzung in Aktionen und Modellkontext sind getrennte Verwendungen derselben Daten.

Metadaten werden gegen ein JSON-Schema validiert, sofern eines im Dashboard konfiguriert ist.

Modellkontext und Autorisierung

Bei vom Besucher kontrollierten Kanälen wie dem Website-Widget und Embed können die Kontaktschlüssel des Besuchers (visitor_name, visitor_email, visitor_phone_number) sowie zulässige Schlüssel, auf die aktive Aktionen verweisen oder die sie erfassen, in den Modellkontext einfließen. Interne und reservierte Werte werden herausgefiltert; außerdem gelten Konfigurations- und Größenbeschränkungen. Für andere Integrationen gelten kanalspezifische Kontextregeln. Ein benutzerdefinierter Schlüssel wie customer_tier oder customer_id ist nicht automatisch für das Modell sichtbar, nur weil Sie ihn übermittelt haben.

Eine Aktion kann {{metadata_<key>}} beim Erstellen ihrer Anfrage ersetzen, ohne die AI zur Generierung dieses Werts aufzufordern. Dadurch werden gewöhnliche Metadaten nicht geheim: Ein zulässiger Wert kann unabhängig davon in den Modellkontext einfließen oder in einer Aktionsantwort erscheinen. Speichern Sie keine API-Schlüssel oder Passwörter in benutzerdefinierten Metadaten.

Vom Browser übermittelte Metadaten sind kein Nachweis für Identität oder Berechtigungen. Ihr empfangender Dienst muss die Identität prüfen und den Zugriff auf private Datensätze autorisieren; eine vom Browser übermittelte Kunden-ID oder Tarifstufe reicht dafür nicht aus. Testen Sie für Ihre Konfiguration sowohl die resultierende Aktionsanfrage als auch die Antwort des Agents.

Get Metadata

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Antwort 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Set Metadata

Metadaten für eine Konversation erstellen oder aktualisieren.

Scope: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Request-Body

Parameter	Description
metadata object, required	Zu speichernde Schlüssel-Wert-Metadaten

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Antwort 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---