KI-Aktions-Variablen

Überall, wo Sie in einer API-Aktion einen Wert eingeben können (URL, Header, Body oder Query-Parameter), können Sie dynamische Werte mit der {{...}}-Syntax einfügen. Quickchat ersetzt diese Platzhalter zum Zeitpunkt der Anfrage, kurz bevor Ihr Endpoint aufgerufen wird.

Klicken Sie auf die Schaltfläche + Add AI Data neben einem beliebigen Wertefeld, um alle im aktuellen Szenario verfügbaren Variablen zu durchsuchen.

Die Schaltfläche + Add AI Data ist neben jedem Wertefeld verfügbar: der Endpoint-URL, jedem Header-Wert, Body-Feldern und Query-Parametern.

Drei Kategorien von Variablen

Kategorie	Syntax	Wann sie gefüllt wird
KI-Parameter. Werte, die Ihr KI‑Agent aus der Konversation extrahiert. Sie definieren sie im Abschnitt Parameters jeder Aktion.	{{order_number}}, {{customer_email}}	Der KI‑Agent füllt sie zum Aufrufzeitpunkt, basierend auf den Regeln, die Sie in der Beschreibung jedes Parameters hinterlegen.
Eingebaute Variablen. Konversationskontext, den Quickchat automatisch einfügt.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Immer verfügbar. Quickchat ersetzt sie bei jeder Anfrage.
Konversations-Metadaten. Benutzerdefinierte Schlüssel-Wert-Paare, die der Konversation zugeordnet sind.	{{metadata_<key>}}	Sobald der entsprechende Schlüssel in der Konversation vorhanden ist (gesetzt vom Widget, einer Kanal-Integration, Smart Data Gathering oder der API).

Tipp

Jede Variable wird im Editor als farbiges Pill dargestellt. Blau bedeutet, es handelt sich um einen KI-Parameter oder eine eingebaute Variable. Orange steht für eine Metadaten-Variable oder ein System-Token. Rot bedeutet, dass der Name keinem Quickchat bekannten Eintrag entspricht (meist ein Tippfehler).

Das ”+ Add AI Data”-Dropdown

Das Dropdown listet alle für das aktuelle Szenario verfügbaren Variablen auf, gruppiert in fünf Abschnitten:

1. Parameters: die KI-Parameter, die Sie für diese Aktion definiert haben.
2. Visitor: vier Metadaten-Schlüssel, die für jeden Besucher automatisch erfasst werden, sofern sein Kanal sie bereitstellt.
3. Metadata (used in recent conversations): benutzerdefinierte Metadaten-Schlüssel aus den letzten 20 Konversationen dieses Szenarios, jeweils mit einem Beispielwert.
4. Built-in: die sechs Konversationsvariablen, die immer verfügbar sind, mit ihrem aktuellen Wert oder einem Beispiel inline.
5. System Tokens: Anmeldedaten, die von einer verbundenen Integration bereitgestellt werden (z. B. HubSpot). Erscheint nur, wenn die Integration verbunden ist.

Das Dropdown gruppiert Variablen in Abschnitten. Built-in-Zeilen zeigen den Live-Wert, sofern bereits bekannt (scenario_id), und e.g. …-Beispiele für die übrigen. Die Gruppe Metadata (used in recent conversations) wird pro Szenario aus echten letzten Konversationen neu aufgebaut. Der Abschnitt System Tokens (hier nicht abgebildet) erscheint nur, wenn eine Integration verbunden ist.

Hinweis

Die Liste Metadata (used in recent conversations) wird aus den letzten 20 Konversationen Ihres Szenarios neu aufgebaut und 5 Minuten lang pro KI‑Agent gecacht. Ein Metadaten-Schlüssel, der in einer brandneuen Konversation gesetzt wird, kann bis zu 5 Minuten benötigen, um in diesem Abschnitt zu erscheinen. Sie können {{metadata_<your_key>}} jederzeit direkt eingeben: Quickchat verlangt nicht, dass der Schlüssel im Dropdown erscheint, damit die Ersetzung funktioniert.

Eingebaute Variablen

Diese sechs Variablen sind immer verfügbar. Das Dropdown + Add AI Data zeigt den Live-Wert (sofern bereits bekannt) oder einen Beispielwert neben jeder Zeile.

Variable	Beispiel	Was es ist
{{scenario_id}}	abc123xyz	ID des KI‑Agenten, zu dem die Konversation gehört.
{{conversation_id}}	conv-d8a8…	Eindeutige Kennung der Konversation.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Direkter Link zur Konversation im Posteingang (Inbox).
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Kanal, über den die Konversation läuft.
{{language}}	en, nl, de, fr, …	ISO-639-1-Code der Konversationssprache (Kleinbuchstaben).
{{country}}	US, GB, NL, DE, …	ISO-3166-1-alpha-2-Ländercode (Großbuchstaben).

Ein paar nützliche Hinweise:

• {{scenario_id}} ist auch in der Browser-URL sichtbar, während Sie die Aktion bearbeiten. Das Dropdown + Add AI Data zeigt die Live-ID des bearbeiteten Szenarios, kein Beispiel.
• {{conversation_url}} ist nützlich, um anklickbare Links in Slack, Jira oder andere Tools zu posten, die von einem direkten Sprung zurück in den Posteingang profitieren.
• {{language}} wird abgeleitet aus (in dieser Reihenfolge): dem URL-Präfix der Seite (für Shopify Markets), Konversations-Metadaten, dann der konfigurierten Sprache Ihres KI‑Agenten.
• {{country}} wird abgeleitet aus (in dieser Reihenfolge): dem URL-Präfix der Seite, der URL-Host-TLD, dann einem Fallback Sprache-zu-Land.

Konversations-Metadaten

Das Präfix metadata_ ist erforderlich. Quickchat sucht <key> in den Metadaten der Konversation und ersetzt seinen Wert in der Anfrage.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Besucher-Metadaten-Schlüssel

Diese vier Schlüssel beschreiben die Sitzung des Besuchers und bekommen einen eigenen Abschnitt Visitor im Dropdown. Sie werden automatisch vom Kanal, von der Integration, vom Widget/Embed oder von der API erfasst. Sie müssen sie nicht selbst übergeben.

Variable	Automatisch erfasst von
{{metadata_fullPathURL}}	Website-Widget, Website-Embed oder Chat-Kanal-Integrationen, die ihr eigenes Widget mitbringen (HubSpot, Intercom usw.).
{{metadata_visitor_name}}	Chat-Kanal-Profil (Telegram, Slack usw.), Kanal-Integrationen, Smart Data Gathering, Ihr Widget/Embed oder die Quickchat-API.
{{metadata_visitor_email}}	Chat-Kanal-Profil, Kanal-Integrationen, Smart Data Gathering, Ihr Widget/Embed oder die Quickchat-API.
{{metadata_visitor_phone_number}}	WhatsApp und andere telefonbewusste Kanäle, Kanal-Integrationen, Smart Data Gathering, Ihr Widget/Embed oder die Quickchat-API.

Benutzerdefinierte Metadaten-Schlüssel

Sie können beliebige Schlüssel-Wert-Paare an eine Konversation anhängen und sie als {{metadata_<key>}} referenzieren.

Vom Website-Widget oder Embed

Übergeben Sie custom_params beim Initialisieren des Widgets. Den vollständigen Code finden Sie im Abschnitt Website-Kanal: Advanced Features: Custom Parameters.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Referenzieren Sie sie in jeder Aktion als {{metadata_order_id}} und {{metadata_customer_tier}}.

Achtung

Metadaten-Schlüssel müssen dem Muster ^[a-zA-Z0-9_]+$ entsprechen (Buchstaben, Ziffern, Unterstriche). Schlüssel mit Leerzeichen oder anderer Interpunktion können nicht als {{metadata_<key>}} referenziert werden. Sie erscheinen weiterhin in der Metadaten-Ansicht der Konversation im Posteingang, werden bei der Aktions-Ersetzung jedoch übersprungen. Bleiben Sie bei snake_case-Namen, wenn Sie sie in Aktionen verwenden möchten.

Vom Smart Data Gathering

Jeder Feldname, den Sie in einer Smart-Data-Gathering-Kampagne konfigurieren, wird zu einem Metadaten-Schlüssel unter demselben Namen. Wenn Ihre Kampagne delivery_address erfasst, können Sie {{metadata_delivery_address}} sofort in jeder nachfolgenden API-Aktion verwenden.

Von Kanal-Integrationen

HubSpot, Intercom, Telegram, Slack, WhatsApp und ähnliche Integrationen schreiben eigene Metadaten in die Konversation (Besuchername, E-Mail, Seiten-URL, Account-Eigenschaften usw.). Alles, was in der Metadaten-Ansicht der Konversation im Posteingang sichtbar ist, lässt sich über {{metadata_<key>}} referenzieren.

Über die Quickchat-API

Verwenden Sie POST /v1/api_core/conversations/{conv_id}/metadata, um Metadaten programmatisch anzuhängen. Siehe Conversation Metadata in der API-Referenz.

Pill-Farben im Editor

Jede {{...}}-Referenz wird als farbiges Pill dargestellt, damit Sie auf einen Blick erkennen, ob Quickchat die Variable kennt.

Pills funktionieren in jedem Wertefeld. Oben: ein oranges Pill {{metadata_user_type}} in der Endpoint-URL und ein blaues Pill {{language}} in einem Header-Wert.

Die gleichen Farbregeln gelten in einem JSON-Request-Body. Eingebaute Variablen wie {{country}} werden blau, Metadaten-Variablen wie {{metadata_fullPathURL}} werden orange dargestellt.

• 🔵 Blau: eine eingebaute Variable oder ein von Ihnen definierter KI-Parameter.
• 🟠 Orange: eine Metadaten-Variable ({{metadata_*}}) oder ein System-Token aus einer verbundenen Integration.
• 🔴 Rot: Quickchat erkennt diesen Namen nicht. Fast immer ein Tippfehler. Korrigieren Sie die Schreibweise, definieren Sie ihn als KI-Parameter oder stellen Sie sicher (falls es wirklich ein Metadaten-Schlüssel ist), dass er mit metadata_ beginnt.

Tipp

{{metadata_anything}} direkt einzugeben ist immer gültig, auch wenn der Schlüssel noch nie in einer Konversation aufgetaucht ist. Das Pill ist orange, nicht rot. Das ist der richtige Weg, um Schlüssel zu verdrahten, die Sie selbst aus einem Widget-Skript oder Smart Data Gathering setzen, bevor die erste Konversation stattgefunden hat.

Ihre Aktion testen

Das Test Response-Sheet (neben Done im Aktions-Editor) ermöglicht es Ihnen, eine echte HTTP-Anfrage zu senden, ohne eine Konversation zu führen. Für jede in der Aktion referenzierte Variable sehen Sie ein Eingabefeld, in dem Sie den Wert eintragen, den Quickchat ersetzen soll.

Zwei praktische Vorbelegungen:

• {{language}} ist standardmäßig auf en gesetzt
• {{country}} ist standardmäßig auf US gesetzt

Überschreiben Sie eines der Felder, um eine andere Locale zu testen. Alle anderen Variablen (Ihre KI-Parameter, {{metadata_*}}-Schlüssel und die übrigen Built-ins) beginnen leer. Geben Sie einen beliebigen Wert ein, um zu simulieren, was in einer Live-Konversation passieren würde.

FAQ

Warum erscheint meine Variable rot? Der Editor erkennt den Namen nicht. Entweder es ist ein Tippfehler, der Name passt zu keinem von Ihnen definierten KI-Parameter, es ist keine eingebaute Variable, oder es handelt sich um einen Metadaten-Schlüssel, dem das Präfix metadata_ fehlt.

Kann ich {{language}} oder {{country}} einfügen, auch wenn ich sie nie setze? Ja. Quickchat leitet beide immer aus dem Konversationskontext ab (Seiten-URL, Browser-Locale oder die konfigurierte Sprache Ihres KI‑Agenten). Sie erhalten immer einen Wert, selbst wenn er auf en / US zurückfällt.

Was ist der Unterschied zwischen {{language}} und {{metadata_locale}}?

• {{language}} ist die eingebaute Variable. Immer verfügbar, immer im Format en / nl / de … Nutzen Sie diese in 99 % der Fälle.
• {{metadata_locale}} existiert nur, wenn eine Kanal-Integration oder Ihr Widget explizit einen locale-Schlüssel in den Konversations-Metadaten gesetzt hat, häufig im Format xx_YY (z. B. en_GB). Greifen Sie nur darauf zurück, wenn Sie die exakte Locale-Zeichenkette wortwörtlich benötigen.

Gibt es eine Obergrenze für die Anzahl der KI-Parameter pro Aktion? Ja, 30 pro Aktion. Falls Sie wirklich mehr benötigen, kontaktieren Sie den Support.

Werden eingebaute und Metadaten-Werte an die KI gesendet? Nein. Sie werden in die HTTP-Anfrage eingefügt, nachdem die KI entschieden hat, die Aktion aufzurufen. Die KI sieht sie nicht und wird nicht aufgefordert, sie zu füllen. Deshalb müssen sie nicht als KI-Parameter definiert werden.

Wie oft wird die Liste „Metadata (used in recent conversations)” aktualisiert? Sie wird pro KI‑Agent 5 Minuten lang gecacht. Ein Metadaten-Schlüssel, der in einer brandneuen Konversation gesetzt wird, kann bis zu 5 Minuten benötigen, um im Dropdown zu erscheinen, aber Sie können {{metadata_<your_key>}} jederzeit direkt eingeben, ohne zu warten.

Sind Metadaten-Schlüsselnamen case-sensitiv? Ja. {{metadata_orderId}} und {{metadata_orderid}} sind unterschiedliche Schlüssel. Verwenden Sie genau die Schreibweise, die Sie auf der Widget-, Integrations- oder API-Seite gesetzt haben.

Kennt das Test-Response-Sheet diese Variablen? Ja. Wenn Ihre Aktion {{language}} oder {{country}} referenziert, belegt das Test-Response-Sheet diese mit en bzw. US vor. Alle anderen Variablen beginnen leer. Geben Sie einen beliebigen Wert ein, um einen Live-Aufruf zu simulieren.

Verwandt

• Custom Actions: wie Sie eine API-Aktion erstellen und konfigurieren.
• Website-Kanal: Custom Parameters: wie Sie Metadaten von Ihrer Website pushen.
• API: Conversation Metadata: wie Sie Metadaten programmatisch pushen.