Variabelen voor AI-acties

Overal waar je een waarde in een API-actie kunt invoeren (URL, headers, body of queryparameters), kun je dynamische waarden invoegen met de syntaxis {{...}}. Quickchat vervangt deze placeholders op het moment van het verzoek, vlak voordat je endpoint wordt aangeroepen.

Klik op + AI-gegevens toevoegen naast een waardeveld om alle beschikbare variabelen voor het huidige scenario te bekijken.

De knop + AI-gegevens toevoegen staat naast elk waardeveld: de endpoint-URL, elke headerwaarde, bodyvelden en queryparameters.

Optionele configuratietools

• Bekijk een voorbeeld van een API-actieverzoek. Vul een opgegeven verzoeksjabloon in met synthetische voorbeeldwaarden zonder het te versturen. Laat authenticatieheaders weg.

• Bekijk een voorbeeld van metadatasleutels. Controleer hoe opgegeven veldnamen variabelesleutels worden, inclusief dubbele namen en fouten met gereserveerde sleutels. Dit inspecteert geen waarden of accountspecifieke machtigingen.

Drie categorieën variabelen

Categorie	Syntaxis	Wanneer de waarde wordt ingevuld
AI-parameters. Waarden die je AI-agent uit het gesprek haalt. Je definieert ze in het onderdeel Parameters van elke actie.	{{order_number}}, {{customer_email}}	De AI-agent vult deze in op het moment van de aanroep, volgens de regels in de beschrijving van elke parameter.
Ingebouwde variabelen. Gesprekscontext die Quickchat automatisch invoegt.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Altijd beschikbaar. Quickchat vervangt ze bij elk verzoek.
Gespreksmetadata. Aangepaste sleutel-waardeparen die aan het gesprek zijn gekoppeld.	{{metadata_<key>}}	Zodra de bijbehorende sleutel in het gesprek bestaat (ingesteld door de widget, een kanaalintegratie, Slimme gegevensverzameling of de API).

Tip

Elke variabele verschijnt als een gekleurde badge in de editor. Blauw betekent een AI-parameter of ingebouwde variabele. Oranje betekent een metadatavariabele of systeemtoken. Rood betekent dat de naam niet overeenkomt met iets wat Quickchat kent (meestal een typefout).

De keuzelijst ”+ AI-gegevens toevoegen”

De keuzelijst toont alle beschikbare variabelen voor het huidige scenario, verdeeld over vijf onderdelen:

1. Parameters: de AI-parameters die je voor deze actie hebt gedefinieerd.
2. Bezoeker: vier metadatasleutels die automatisch voor elke bezoeker worden vastgelegd wanneer het kanaal ze aanlevert.
3. Metadata (gebruikt in recente gesprekken): aangepaste metadatasleutels uit de laatste 20 gesprekken van dit scenario, met voor elke sleutel een voorbeeldwaarde.
4. Ingebouwd: de zeven gespreksvariabelen die altijd beschikbaar zijn, met hun huidige waarde of een voorbeeld ernaast.
5. Systeemtokens: inloggegevens van een verbonden integratie (bijvoorbeeld HubSpot of Telegram). Verschijnt alleen als de integratie is verbonden. Zie Systeemtokens hieronder.

De keuzelijst groepeert variabelen in onderdelen. De regels onder Ingebouwd tonen de actuele waarde als die al bekend is (scenario_id) en voor de overige variabelen voorbeelden met e.g. …. De groep Metadata (gebruikt in recente gesprekken) wordt per scenario opgebouwd uit echte recente gesprekken. Het onderdeel Systeemtokens (hier niet afgebeeld) verschijnt alleen wanneer een integratie is verbonden.

Opmerking

De lijst Metadata (gebruikt in recente gesprekken) wordt opgebouwd uit de 20 meest recente gesprekken van je scenario en 5 minuten per AI-agent gecachet. Een metadatasleutel uit een nieuw gesprek kan daardoor pas na maximaal 5 minuten verschijnen. Je kunt altijd rechtstreeks {{metadata_<your_key>}} invoeren: de sleutel hoeft niet in de keuzelijst te staan om de vervanging te laten werken.

Ingebouwde variabelen

Deze zeven variabelen zijn altijd beschikbaar. De keuzelijst + AI-gegevens toevoegen toont naast elke regel de actuele waarde (als die bekend is) of een voorbeeldwaarde.

Variabele	Voorbeeld	Betekenis
{{scenario_id}}	abc123xyz	ID van de AI-agent waartoe het gesprek behoort.
{{conversation_id}}	conv-d8a8…	Unieke identificatie van het gesprek.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Rechtstreekse Inbox-link naar dit gesprek.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Kanaal waarop het gesprek plaatsvindt.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Huidige UTC-datum en -tijd in ISO 8601-formaat.
{{language}}	en, nl, de, fr, …	ISO 639-1-code van de gesprekstaal in kleine letters.
{{country}}	US, GB, NL, DE, …	ISO 3166-1 alpha-2-landcode in hoofdletters.

Enkele zaken om rekening mee te houden:

• {{scenario_id}} staat ook in de URL van je browser terwijl je de actie bewerkt. De keuzelijst + AI-gegevens toevoegen toont het actuele ID van het scenario dat je bewerkt, geen voorbeeld.
• {{conversation_url}} is handig om klikbare links in Slack, Jira of een andere tool te plaatsen waarmee je direct naar de Inbox wilt kunnen gaan.
• {{language}} wordt afgeleid van, in deze volgorde: het URL-voorvoegsel van de pagina (voor Shopify Markets), gespreksmetadata en vervolgens de ingestelde taal van je AI-agent.
• {{country}} wordt afgeleid van, in deze volgorde: het URL-voorvoegsel van de pagina, het topleveldomein van de URL en vervolgens een terugvaloptie op basis van de taal.

Gespreksmetadata

Het voorvoegsel metadata_ is verplicht. Quickchat zoekt <key> op in de metadata van het gesprek en voegt de waarde in het verzoek in.

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

Metadatasleutels voor bezoekers

Deze vier sleutels beschrijven de sessie van de bezoeker en hebben een eigen onderdeel Bezoeker in de keuzelijst. Ze kunnen worden vastgelegd door het kanaal, de integratie, widget/embed, API, Slimme gegevensverzameling of ingestelde koppelingen van actie-invoer.

Variabele	Automatisch vastgelegd door
{{metadata_fullPathURL}}	Websitewidget, website-embed of chatkanaalintegraties met een eigen widget (HubSpot, Intercom enzovoort).
{{metadata_visitor_name}}	Profiel van het chatkanaal (Telegram, Slack enzovoort), kanaalintegraties, Slimme gegevensverzameling, ingestelde koppelingen van actie-invoer, je widget/embed of de Quickchat-API.
{{metadata_visitor_email}}	Profiel van het chatkanaal, kanaalintegraties, Slimme gegevensverzameling, ingestelde koppelingen van actie-invoer, je widget/embed of de Quickchat-API.
{{metadata_visitor_phone_number}}	WhatsApp en andere kanalen met telefoonnummers, kanaalintegraties, Slimme gegevensverzameling, ingestelde koppelingen van actie-invoer, je widget/embed of de Quickchat-API.

Aangepaste metadatasleutels

Je kunt willekeurige sleutel-waardeparen aan een gesprek koppelen en ernaar verwijzen met {{metadata_<key>}}.

Vanuit de websitewidget of embed

Geef custom_params mee wanneer je de widget initialiseert. Zie Websitekanaal: Geavanceerde functies: Aangepaste parameters voor het volledige codevoorbeeld.

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

Verwijs er in elke actie naar met {{metadata_order_id}} en {{metadata_customer_tier}}.

Opgepast

Metadatasleutels moeten overeenkomen met ^[a-zA-Z0-9_]+$ (letters, cijfers en underscores). Sleutels met spaties of andere leestekens kunnen niet worden gebruikt als {{metadata_<key>}}. Ze blijven zichtbaar in de metadataweergave van het gesprek in de Inbox, maar worden overgeslagen bij vervanging in de actie. Gebruik snake_case-namen als je ze in acties wilt gebruiken.

Vanuit Slimme gegevensverzameling

Elk ingeschakeld gegevenspunt in Slimme gegevensverzameling wordt een metadatasleutel op basis van zijn naam in kleine letters en snake_case: spaties worden underscores, accenten vervallen en andere leestekens worden verwijderd.

Gegevenspunt	Variabele
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

Contactgegevens vormen de uitzondering. Een gegevenspunt met de naam Email, Name of Phone number (of een vergelijkbare Engelse variant zoals Email address, Full name of Mobile) vult respectievelijk {{metadata_visitor_email}}, {{metadata_visitor_name}} of {{metadata_visitor_phone_number}}. Alleen Engelse namen worden herkend: een gegevenspunt met de naam Correo electrónico krijgt zijn eigen sleutel, correo_electronico. Wanneer de AI-agent een contactgegeven vastlegt dat het gesprek nog niet bevatte, zet hij ook lead_captured op true.

• Leeg totdat de waarde is vastgelegd. De sleutel wordt met een lege waarde toegevoegd wanneer de AI-agent voor het eerst antwoordt met Slimme gegevensverzameling ingeschakeld, en wordt gevuld zodra de bezoeker het gegeven aanlevert. Een latere correctie werkt de waarde bij; deze wordt nooit meer leeggemaakt.
• Gebruik is true om op een waarde te wachten. Bij Uitvoeren wanneer slaagt budget is true zodra een waarde is vastgelegd, terwijl budget exists al slaagt zodra Slimme gegevensverzameling heeft gedraaid. Antwoorden zoals no, false of 0 tellen als onwaar.
• Je eigen waarden hebben voorrang. Als de sleutel al een waarde bevat die door je website, de API of een andere actie is ingesteld, laat Slimme gegevensverzameling deze ongemoeid. Het bijwerken stopt ook zodra iets anders de sleutel wijzigt.
• Enkele namen zijn gereserveerd, zoals language, locale en lead_captured. Een gegevenspunt met een van deze namen wordt geen variabele. Hernoem het als je een variabele nodig hebt.
• Een gegevenspunt hernoemen hernoemt ook de variabele. Werk acties bij die de variabele gebruiken: een actie kan niet worden uitgevoerd zolang een benodigde variabele in het gesprek ontbreekt.

Zodra een gesprek de sleutel bevat, verschijnt deze ook in de keuzelijst + AI-gegevens toevoegen.

Controleer uitvoeringsvoorwaarden van acties met voorbeeldmetadata om te zien welke voorwaarden slagen. De controle evalueert de opgegeven waarden zonder een actie uit te voeren.

Vanuit de invoer of het antwoord van een actie

Een API-actie kan een opgegeven invoerwaarde of een waarde uit het API-antwoord in een metadatasleutel opslaan, zodat een latere actie deze kan hergebruiken. Kies bij Opslaan in geheugen de Bron: Actie-invoer of API-antwoord. Selecteer onder Op te slaan waarde voor invoer een actieparameter in de keuzelijst, of voer voor antwoorden een JSONPath-expressie in. Kies daarna een Geheugensleutel. Verwijs naar de waarde met {{metadata_<memory key>}}.

Invoerkoppelingen naar visitor_name, visitor_phone_number en visitor_email vullen ook lege contactvelden in de Inbox. Bestaande waarden en velden die een medewerker expliciet heeft gewist, blijven behouden. Invoer wordt opgeslagen vóór het HTTP-verzoek zodra de actie haar controles doorstaat, zodat geldige contactgegevens beschikbaar blijven als de API faalt. Zie Opslaan in geheugen voor voorbeelden en de volledige uitleg.

Vanuit kanaalintegraties

HubSpot, Intercom, Telegram, Slack, WhatsApp en vergelijkbare integraties voegen hun eigen metadata aan het gesprek toe (naam van de bezoeker, e-mailadres, pagina-URL, accounteigenschappen enzovoort). Alles wat zichtbaar is in de metadataweergave van het gesprek in de Inbox, kan worden gebruikt via {{metadata_<key>}}.

Vanuit de Quickchat-API

Gebruik POST /v1/api_core/conversations/{conv_id}/metadata om metadata programmatisch toe te voegen. Zie Gespreksmetadata in de API-referentie.

Systeemtokens

Sommige verbonden integraties stellen een systeemtoken beschikbaar: inloggegevens die Quickchat op de server, op het moment van de aanroep in het verzoek invoegt wanneer de actie wordt uitgevoerd. Een systeemtoken wordt niet aan de context van de AI of aan gespreksmetadata toegevoegd en wordt afgeschermd in het verzoeklogboek, de trace en het aanroeplogboek in de Inbox. Gewone metadata heeft niet dezelfde garanties voor geheimhouding. Het token verschijnt alleen in het onderdeel Systeemtokens van de keuzelijst + AI-gegevens toevoegen wanneer de bijbehorende integratie is verbonden, en wordt als oranje badge weergegeven.

Systeemtoken	Beschikbaar wanneer	Wat wordt ingevoegd
{{hubspot_access_token}}	HubSpot is verbonden	Een geldig HubSpot OAuth-toegangstoken dat automatisch wordt vernieuwd.
{{telegram_bot_token}}	Het scenario Telegram-activiteit heeft	Het token van je verbonden Telegram-bot, voor aanroepen naar de Telegram Bot API.

De Telegram Bot API aanroepen

De Telegram Bot API verwacht het bottoken in het URL-pad, dus je verwijst er rechtstreeks naar in de endpoint-URL:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

Quickchat vult het token in op het moment van de aanroep en schermt het overal af waar het verzoek zichtbaar is, zodat het geheim niet uitlekt. Om een Bot API-aanroep op de huidige chat, het huidige bericht of de afzender te richten, combineer je het met de Telegram-metadatasleutels die Quickchat op elk binnenkomend bericht instelt:

Metadatasleutel	Waarde
{{metadata_telegram_chat_id}}	De chat waaruit het bericht afkomstig is.
{{metadata_telegram_chat_type}}	private, group, supergroup of channel.
{{metadata_telegram_user_id}}	Het Telegram-gebruikers-ID van de afzender.
{{metadata_telegram_username}}	De @username van de afzender, als die er een heeft.
{{metadata_telegram_message_id}}	Het ID van het binnenkomende bericht.
{{metadata_telegram_sender_is_admin}}	true wanneer de afzender een beheerder van de chat is. Wordt op de server bepaald en kan dus niet vanuit de chat worden vervalst. Gebruik dit in een uitvoeringsvoorwaarde om moderatieacties tot beheerders te beperken.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Worden ingesteld als het binnenkomende bericht een antwoord is, zodat de AI het oorspronkelijke bericht kan verwerken (bijvoorbeeld de auteur modereren).

Badgekleuren in de editor

Elke verwijzing met {{...}} wordt als gekleurde badge weergegeven, zodat je direct ziet of Quickchat de variabele herkent.

Badges werken in elk waardeveld. Hierboven: een oranje badge {{metadata_user_type}} in de endpoint-URL en een blauwe badge {{language}} in een headerwaarde.

Dezelfde kleurregels gelden binnen een JSON-verzoekbody. Ingebouwde variabelen zoals {{country}} zijn blauw; metadatavariabelen zoals {{metadata_fullPathURL}} zijn oranje.

• 🔵 Blauw: een ingebouwde variabele of een AI-parameter die je hebt gedefinieerd.
• 🟠 Oranje: een metadatavariabele ({{metadata_*}}) of een systeemtoken van een verbonden integratie.
• 🔴 Rood: Quickchat herkent deze naam niet. Bijna altijd een typefout. Corrigeer de spelling, definieer de naam als AI-parameter of zorg (als het echt een metadatasleutel is) dat deze met metadata_ begint.

Tip

Rechtstreeks {{metadata_anything}} invoeren is altijd geldig, ook als de sleutel nog nooit in een gesprek is voorgekomen. De badge wordt oranje, niet rood. Dit is de juiste manier om sleutels te koppelen die je zelf via een widgetscript of Slimme gegevensverzameling instelt voordat het eerste gesprek heeft plaatsgevonden.

Je actie testen

In het paneel Antwoord testen (naast Klaar in de actie-editor) kun je een echt HTTP-verzoek versturen zonder een chat te doorlopen. Voor elke variabele waarnaar de actie verwijst, zie je een invoerregel waarin je de waarde invult die Quickchat zal gebruiken.

Het paneel vult elke ingebouwde variabele vooraf in met actuele context of een representatieve testwaarde. De standaardwaarden voor taal, land en tijd zijn onder meer:

• {{language}} staat standaard op en
• {{country}} staat standaard op US
• {{current_timestamp}} staat standaard op de huidige UTC-tijd

Pas elk veld aan om een andere waarde te testen. Je AI-parameters en sleutels met {{metadata_*}} zijn aanvankelijk leeg. Vul een waarde in om te simuleren wat er in een echt gesprek zou gebeuren.

Veelgestelde vragen

Waarom wordt mijn variabele rood weergegeven? De editor herkent de naam niet. Er staat een typefout in, de naam komt niet overeen met een gedefinieerde AI-parameter, het is geen ingebouwde variabele of het is een metadatasleutel zonder het voorvoegsel metadata_.

Kan ik {{language}} of {{country}} invoegen als ik ze nooit heb ingesteld? Ja. Quickchat leidt beide altijd af van de gesprekscontext (pagina-URL, browserlocale of de ingestelde taal van je AI-agent). Je krijgt altijd een waarde, ook als deze terugvalt op en / US.

Wat is het verschil tussen {{language}} en {{metadata_locale}}?

• {{language}} is de ingebouwde variabele. Altijd beschikbaar, altijd in de vorm en / nl / de … Gebruik deze in 99% van de gevallen.
• {{metadata_locale}} bestaat alleen als een kanaalintegratie of je widget expliciet een sleutel locale in de gespreksmetadata heeft ingesteld, vaak in de vorm xx_YY (bijvoorbeeld en_GB). Gebruik deze alleen wanneer je de exacte localestring ongewijzigd nodig hebt.

Is er een limiet op het aantal AI-parameters per actie? Ja, 30 per actie. Heb je echt meer nodig, neem dan contact op met support.

Worden ingebouwde waarden en metadatawaarden naar de AI gestuurd? Quickchat vult deze waarden in tijdens het opbouwen van het HTTP-verzoek. De AI hoeft ze niet te genereren of als AI-parameters te definiëren. Voor een actie met AI beslist gebeurt de vervanging nadat de AI de actie heeft gekozen. Bij automatische acties wordt de AI niet gevraagd de actie te kiezen.

Vervanging en modelcontext staan los van elkaar. Geschikte metadata en ingebouwde context kunnen ook beschikbaar zijn voor de AI, en het antwoord van een actie kan dezelfde waarden bevatten. Andere metadata wordt uit de prompt gefilterd. Ga er niet van uit dat gewone metadata altijd zichtbaar of altijd verborgen is voor het model. Zie Modelcontext en autorisatie.

Hoe vaak wordt de lijst “Metadata (gebruikt in recente gesprekken)” vernieuwd? Deze wordt 5 minuten per AI-agent gecachet. Een metadatasleutel uit een nieuw gesprek kan pas na maximaal 5 minuten in de keuzelijst verschijnen, maar je kunt altijd zonder te wachten rechtstreeks {{metadata_<your_key>}} invoeren.

Zijn namen van metadatasleutels hoofdlettergevoelig? Ja. {{metadata_orderId}} en {{metadata_orderid}} zijn verschillende sleutels. Gebruik precies dezelfde hoofdletters als aan de kant van je widget, integratie of API.

Kent het paneel Antwoord testen deze variabelen? Ja. Het paneel Antwoord testen vult alle zeven ingebouwde variabelen vooraf in, waaronder {{language}} met en, {{country}} met US en {{current_timestamp}} met de huidige UTC-tijd. AI-parameters en metadatavariabelen zijn aanvankelijk leeg. Vul een waarde in om een echte aanroep te simuleren.

Gerelateerd

• Aangepaste acties: een API-actie aanmaken en configureren.
• Websitekanaal: Aangepaste parameters: metadata vanuit je website doorgeven.
• API: Gespreksmetadata: metadata programmatisch doorgeven.