Variabili delle azioni AI

In qualsiasi punto di un’azione API in cui puoi digitare un valore (URL, header, corpo o parametri di query), puoi inserire valori dinamici usando la sintassi {{...}}. Quickchat sostituisce questi segnaposto al momento della richiesta, subito prima di chiamare il tuo endpoint.

Fai clic sul pulsante + Aggiungi dati AI accanto a qualsiasi campo di valore per esplorare tutte le variabili disponibili nello scenario corrente.

Il pulsante + Aggiungi dati AI è disponibile accanto a ogni campo di valore: URL dell’endpoint, valori degli header, campi del corpo e parametri di query.

Strumenti di configurazione facoltativi

• Visualizza un’anteprima di una richiesta di azione API. Compila un modello di richiesta fornito usando valori di esempio sintetici senza inviarlo. Ometti gli header con credenziali.

• Visualizza un’anteprima delle chiavi dei metadati. Verifica come i nomi dei campi forniti diventano chiavi di variabili, inclusi nomi duplicati ed errori relativi a chiavi riservate. Questo strumento non esamina i valori o le autorizzazioni specifiche dell’account.

Tre categorie di variabili

Categoria	Sintassi	Quando viene compilata
Parametri AI. Valori che il tuo agente AI estrae dalla conversazione. Li definisci nella sezione Parametri di ogni azione.	{{order_number}}, {{customer_email}}	L’agente AI li compila al momento della chiamata, in base alle regole scritte nella descrizione di ogni parametro.
Variabili predefinite. Contesto della conversazione inserito automaticamente da Quickchat.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Sempre disponibili. Quickchat le sostituisce a ogni richiesta.
Metadati della conversazione. Coppie chiave-valore personalizzate associate alla conversazione.	{{metadata_<key>}}	Quando la chiave corrispondente esiste nella conversazione (impostata dal widget, da un’integrazione di canale, dalla Raccolta intelligente dei dati o dall’API).

Consiglio

Ogni variabile viene visualizzata come un riquadro colorato nell’editor. Il blu indica un parametro AI o una variabile predefinita. L’arancione indica una variabile dei metadati o un token di sistema. Il rosso indica che il nome non corrisponde a nulla di noto a Quickchat (di solito è un errore di battitura).

Il menu a discesa ”+ Aggiungi dati AI”

Il menu a discesa elenca tutte le variabili disponibili per lo scenario corrente, suddivise in cinque sezioni:

1. Parametri: i parametri AI definiti per questa azione.
2. Visitatore: quattro chiavi dei metadati acquisite automaticamente per ogni visitatore, quando il canale le fornisce.
3. Metadati (usati nelle conversazioni recenti): chiavi dei metadati personalizzate presenti nelle ultime 20 conversazioni dello scenario, con un valore di esempio per ciascuna.
4. Integrato: le sette variabili di conversazione sempre disponibili, con il valore corrente o un esempio mostrato nella stessa riga.
5. Token di sistema: credenziali fornite da un’integrazione collegata (ad esempio HubSpot o Telegram). Compare soltanto se l’integrazione è collegata. Vedi Token di sistema di seguito.

Il menu raggruppa le variabili in sezioni. Le righe Integrato mostrano il valore effettivo dove è già noto (scenario_id) ed esempi e.g. … per le altre. Il gruppo Metadati (usati nelle conversazioni recenti) viene ricostruito per ogni scenario a partire da conversazioni recenti reali. La sezione Token di sistema (non mostrata qui) compare soltanto quando è collegata un’integrazione.

Nota

L’elenco Metadati (usati nelle conversazioni recenti) viene ricostruito dalle 20 conversazioni più recenti dello scenario e memorizzato nella cache per 5 minuti per ogni agente AI. Una chiave dei metadati impostata in una nuova conversazione può impiegare fino a 5 minuti per comparire in questa sezione. Puoi sempre digitare direttamente {{metadata_<your_key>}}: Quickchat non richiede che la chiave compaia nel menu affinché la sostituzione funzioni.

Variabili predefinite

Queste sette variabili sono sempre disponibili. Il menu + Aggiungi dati AI mostra il valore effettivo (dove è già noto) o un valore di esempio accanto a ogni riga.

Variabile	Esempio	Significato
{{scenario_id}}	abc123xyz	ID dell’agente AI a cui appartiene la conversazione.
{{conversation_id}}	conv-d8a8…	Identificatore univoco della conversazione.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Link diretto a questa conversazione in Posta in arrivo.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Canale su cui si svolge la conversazione.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Data e ora UTC correnti in formato ISO 8601.
{{language}}	en, nl, de, fr, …	Codice ISO 639-1 in minuscolo della lingua della conversazione.
{{country}}	US, GB, NL, DE, …	Codice del paese ISO 3166-1 alpha-2 in maiuscolo.

Alcuni dettagli utili:

• {{scenario_id}} è visibile anche nell’URL del browser mentre modifichi l’azione. Il menu + Aggiungi dati AI mostra l’ID effettivo dello scenario che stai modificando, non un esempio.
• {{conversation_url}} è utile per pubblicare link cliccabili in Slack, Jira o altri strumenti in cui serve tornare direttamente a Posta in arrivo.
• {{language}} viene ricavata, in quest’ordine, dal prefisso dell’URL della pagina (per Shopify Markets), dai metadati della conversazione e infine dalla lingua configurata per l’agente AI.
• {{country}} viene ricavata, in quest’ordine, dal prefisso dell’URL della pagina, dal dominio di primo livello dell’host dell’URL e infine da un’associazione di riserva tra lingua e paese.

Metadati della conversazione

Il prefisso metadata_ è obbligatorio. Quickchat cerca <key> nei metadati della conversazione e ne sostituisce il valore nella richiesta.

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

Chiavi dei metadati del visitatore

Queste quattro chiavi descrivono la sessione del visitatore e hanno una sezione Visitatore dedicata nel menu a discesa. Possono essere acquisite dal canale, da un’integrazione, dal widget o dalla chat incorporata, dall’API, dalla Raccolta intelligente dei dati o dalle mappature configurate degli input delle azioni.

Variabile	Acquisita automaticamente da
{{metadata_fullPathURL}}	Widget del sito web, chat incorporata nel sito o integrazioni di canali di chat che includono un proprio widget (HubSpot, Intercom e così via).
{{metadata_visitor_name}}	Profilo del canale di chat (Telegram, Slack e così via), integrazioni di canale, Raccolta intelligente dei dati, mappature configurate degli input delle azioni, il tuo widget o la tua chat incorporata, oppure l’API di Quickchat.
{{metadata_visitor_email}}	Profilo del canale di chat, integrazioni di canale, Raccolta intelligente dei dati, mappature configurate degli input delle azioni, il tuo widget o la tua chat incorporata, oppure l’API di Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp e altri canali che conoscono il numero di telefono, integrazioni di canale, Raccolta intelligente dei dati, mappature configurate degli input delle azioni, il tuo widget o la tua chat incorporata, oppure l’API di Quickchat.

Chiavi dei metadati personalizzate

Puoi associare coppie chiave-valore arbitrarie a una conversazione e richiamarle come {{metadata_<key>}}.

Dal widget del sito web o dalla chat incorporata

Passa custom_params quando inizializzi il widget. Consulta la sezione Canale sito web: funzionalità avanzate: parametri personalizzati per il frammento completo.

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

Richiamali in qualsiasi azione come {{metadata_order_id}} e {{metadata_customer_tier}}.

Attenzione

Le chiavi dei metadati devono corrispondere a ^[a-zA-Z0-9_]+$ (lettere, cifre e trattini bassi). Le chiavi contenenti spazi o altra punteggiatura non possono essere richiamate come {{metadata_<key>}}. Continueranno a comparire nella vista dei metadati della conversazione in Posta in arrivo, ma la sostituzione nell’azione le ignorerà. Usa nomi snake_case quando intendi impiegarle nelle azioni.

Dalla Raccolta intelligente dei dati

Ogni dato abilitato nella Raccolta intelligente dei dati diventa una chiave dei metadati con lo stesso nome in snake_case minuscolo: gli spazi diventano trattini bassi, gli accenti vengono eliminati e gli altri segni di punteggiatura vengono rimossi.

Dato	Variabile
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

I recapiti fanno eccezione. Un dato chiamato Email, Name o Phone number (oppure una variante inglese simile, come Email address, Full name o Mobile) compila invece {{metadata_visitor_email}}, {{metadata_visitor_name}} o {{metadata_visitor_phone_number}}. Vengono riconosciuti soltanto i nomi inglesi: un dato chiamato Correo electrónico diventa una chiave autonoma, correo_electronico. Quando l’agente AI acquisisce un recapito non ancora presente nella conversazione, imposta anche lead_captured su true.

• Vuota fino all’acquisizione. La chiave viene aggiunta con un valore vuoto la prima volta che l’agente AI risponde con la Raccolta intelligente dei dati attiva e viene compilata quando il visitatore fornisce l’informazione. Una correzione successiva la aggiorna; non viene più svuotata.
• Usa is true per attendere un valore. In Esegui quando, budget is true è soddisfatta quando viene acquisito un valore, mentre budget exists è soddisfatta appena la Raccolta intelligente dei dati è stata eseguita. Risposte come no, false o 0 contano come false.
• I tuoi valori hanno la precedenza. Se la chiave contiene già un valore impostato dal tuo sito web, dall’API o da un’altra azione, la Raccolta intelligente dei dati non lo modifica. Inoltre smette di aggiornare una chiave quando qualcos’altro la modifica.
• Alcuni nomi sono riservati, ad esempio language, locale e lead_captured. Un dato con uno di questi nomi non diventa una variabile: rinominalo se te ne serve una.
• Rinominare un dato rinomina la sua variabile. Aggiorna le azioni che la usano: un’azione non può essere eseguita se nella conversazione manca una variabile necessaria.

Quando una conversazione contiene la chiave, questa compare anche nel menu + Aggiungi dati AI.

Verifica le condizioni di esecuzione delle azioni su metadati di esempio per vedere quali vengono soddisfatte. La verifica valuta i valori forniti senza eseguire un’azione.

Dagli input o dalla risposta di un’azione

Un’azione API può salvare un input dichiarato o un valore della risposta API in una chiave dei metadati, affinché un’azione successiva possa riutilizzarlo. In Salva in memoria, scegli Input dell’Azione o Risposta API come Fonte. In Valore da salvare, seleziona un parametro dell’azione dal menu a discesa per gli input oppure inserisci un’espressione JSONPath per le risposte, quindi scegli una Chiave di memoria. Richiama il valore come {{metadata_<memory key>}}.

Le mappature degli input verso visitor_name, visitor_phone_number e visitor_email compilano anche i campi di contatto non impostati in Posta in arrivo. I valori esistenti e i campi esplicitamente cancellati da un operatore vengono conservati. Gli input vengono salvati prima della richiesta HTTP, una volta superate le verifiche dell’azione, così i recapiti validi rimangono disponibili anche se l’API fallisce. Consulta Salva in memoria per esempi e istruzioni complete.

Dalle integrazioni di canale

HubSpot, Intercom, Telegram, Slack, WhatsApp e integrazioni simili inviano i propri metadati alla conversazione (nome del visitatore, email, URL della pagina, proprietà dell’account e così via). Tutto ciò che è visibile nella vista dei metadati della conversazione in Posta in arrivo può essere richiamato tramite {{metadata_<key>}}.

Dall’API di Quickchat

Usa POST /v1/api_core/conversations/{conv_id}/metadata per associare metadati in modo programmatico. Consulta Metadati della conversazione nel riferimento API.

Token di sistema

Alcune integrazioni collegate espongono un token di sistema: una credenziale che Quickchat inserisce nella richiesta lato server, al momento della chiamata, quando l’azione viene eseguita. Un token di sistema non viene aggiunto al contesto dell’AI o ai metadati della conversazione e viene oscurato nel registro delle richieste, nella traccia e nel registro delle chiamate di Posta in arrivo. I metadati ordinari non offrono le stesse garanzie di riservatezza. Il token compare nella sezione Token di sistema del menu + Aggiungi dati AI soltanto quando l’integrazione corrispondente è collegata ed è visualizzato in un riquadro arancione.

Token di sistema	Disponibile quando	Cosa inserisce
{{hubspot_access_token}}	HubSpot è collegato	Un token di accesso OAuth HubSpot valido, aggiornato automaticamente.
{{telegram_bot_token}}	Lo scenario ha attività Telegram	Il token del tuo bot Telegram collegato, per chiamare la Telegram Bot API.

Chiamare la Telegram Bot API

La Telegram Bot API richiede il token del bot nel percorso dell’URL, quindi lo richiami direttamente nell’URL dell’endpoint:

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

Quickchat risolve il token al momento della chiamata e lo oscura ovunque venga mostrata la richiesta, evitando di esporre il segreto. Per indirizzare una chiamata Bot API alla chat, al messaggio o al mittente corrente, abbinalo alle chiavi dei metadati Telegram impostate da Quickchat per ogni messaggio in arrivo:

Chiave dei metadati	Valore
{{metadata_telegram_chat_id}}	La chat da cui proviene il messaggio.
{{metadata_telegram_chat_type}}	private, group, supergroup o channel.
{{metadata_telegram_user_id}}	L’ID utente Telegram del mittente.
{{metadata_telegram_username}}	Il @nomeutente del mittente, se presente.
{{metadata_telegram_message_id}}	L’ID del messaggio in arrivo.
{{metadata_telegram_sender_is_admin}}	true quando il mittente è un amministratore della chat. Calcolato lato server, quindi non può essere falsificato dalla chat. Usalo in una condizione di esecuzione per riservare le azioni di moderazione agli amministratori.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Impostate quando il messaggio in arrivo è una risposta, così l’AI può agire sul messaggio a cui si risponde (ad esempio moderarne l’autore).

Colori dei riquadri nell’editor

Ogni riferimento {{...}} viene visualizzato in un riquadro colorato, così puoi capire subito se Quickchat riconosce la variabile.

I riquadri funzionano in tutti i campi di valore. Sopra: un riquadro arancione {{metadata_user_type}} nell’URL dell’endpoint e uno blu {{language}} nel valore di un header.

Le stesse regole di colore valgono nel corpo JSON di una richiesta. Le variabili predefinite come {{country}} sono blu, quelle dei metadati come {{metadata_fullPathURL}} sono arancioni.

• 🔵 Blu: una variabile predefinita o un parametro AI che hai definito.
• 🟠 Arancione: una variabile dei metadati ({{metadata_*}}) o un token di sistema di un’integrazione collegata.
• 🔴 Rosso: Quickchat non riconosce questo nome. Quasi sempre è un errore di battitura. Correggilo, definiscilo come parametro AI oppure, se è effettivamente una chiave dei metadati, assicurati che inizi con metadata_.

Consiglio

Digitare direttamente {{metadata_anything}} è sempre valido, anche se la chiave non è ancora comparsa in alcuna conversazione. Il riquadro sarà arancione, non rosso. È il modo corretto per predisporre chiavi che imposti tramite uno script del widget o la Raccolta intelligente dei dati prima che avvenga la prima conversazione.

Provare l’azione

Il pannello Testa risposta (accanto a Fatto nell’editor dell’azione) consente di inviare una richiesta HTTP reale senza passare da una chat. Per ogni variabile richiamata nell’azione vedrai una riga in cui inserire il valore che Quickchat sostituirà.

Il pannello precompila tutte le variabili predefinite con il contesto effettivo o un valore di test rappresentativo. I valori predefiniti per localizzazione e ora includono:

• {{language}} usa per impostazione predefinita en
• {{country}} usa per impostazione predefinita US
• {{current_timestamp}} usa per impostazione predefinita l’ora UTC corrente

Modifica qualsiasi campo per provare un valore diverso. I parametri AI e le chiavi {{metadata_*}} sono inizialmente vuoti. Digita un valore per simulare ciò che accadrebbe in una conversazione reale.

Domande frequenti

Perché la mia variabile compare in rosso? L’editor non riconosce il nome. Potrebbe esserci un errore di battitura, il nome potrebbe non corrispondere a un parametro AI definito o a una variabile predefinita, oppure potrebbe essere una chiave dei metadati priva del prefisso metadata_.

Posso inserire {{language}} o {{country}} anche se non le ho mai impostate? Sì. Quickchat le ricava sempre dal contesto della conversazione (URL della pagina, localizzazione del browser o lingua configurata per l’agente AI). Riceverai sempre un valore, anche se sarà il valore di riserva en / US.

Qual è la differenza tra {{language}} e {{metadata_locale}}?

• {{language}} è la variabile predefinita. È sempre disponibile, sempre nel formato en / nl / de … Usala nel 99% dei casi.
• {{metadata_locale}} esiste soltanto se un’integrazione di canale o il tuo widget ha impostato esplicitamente una chiave locale nei metadati della conversazione, spesso in formato xx_YY (ad esempio en_GB). Usala soltanto quando ti serve la stringa esatta della localizzazione senza modifiche.

Esiste un limite al numero di parametri AI per azione? Sì, 30 per azione. Se te ne servono effettivamente di più, contatta l’assistenza.

I valori predefiniti e dei metadati vengono inviati all’AI? Quickchat sostituisce questi valori durante la costruzione della richiesta HTTP; l’AI non deve generarli o definirli come parametri AI. Per un’azione Decide l’AI, la sostituzione avviene dopo che l’AI ha scelto l’azione. Le azioni automatiche non chiedono all’AI di sceglierle.

La sostituzione e il contesto del modello sono aspetti separati. I metadati idonei e il contesto predefinito possono anche essere disponibili all’AI e la risposta di un’azione può contenere gli stessi valori. Altri metadati vengono esclusi dal prompt. Non presumere che i metadati ordinari siano sempre visibili o sempre nascosti al modello. Consulta Contesto del modello e autorizzazione.

Ogni quanto viene aggiornato l’elenco “Metadati (usati nelle conversazioni recenti)”? Viene memorizzato nella cache per 5 minuti per ogni agente AI. Una chiave dei metadati impostata in una nuova conversazione può impiegare fino a 5 minuti per comparire nel menu, ma puoi sempre digitare direttamente {{metadata_<your_key>}} senza aspettare.

I nomi delle chiavi dei metadati distinguono maiuscole e minuscole? Sì. {{metadata_orderId}} e {{metadata_orderid}} sono chiavi diverse. Usa esattamente le stesse maiuscole e minuscole impostate nel widget, nell’integrazione o nell’API.

Il pannello Testa risposta riconosce queste variabili? Sì. Il pannello Testa risposta precompila tutte e sette le variabili predefinite, incluse {{language}} con en, {{country}} con US e {{current_timestamp}} con l’ora UTC corrente. I parametri AI e le variabili dei metadati sono inizialmente vuoti. Digita un valore per simulare una chiamata reale.

Risorse correlate

• Azioni personalizzate: come creare e configurare un’azione API.
• Canale sito web: parametri personalizzati: come inviare metadati dal tuo sito web.
• API: metadati della conversazione: come inviare metadati in modo programmatico.