Variabili Globali - Riferimento delle Variabili di Sistema per ChatMaxima

Riferimento alle Variabili Globali di ChatMaxima (campi di sistema sys_) usate per personalizzare bot, broadcast e risposte automatiche con dati di contatto e sessione.

Panoramica

Le Variabili Globali, dette anche Variabili di Sistema, sono segnaposto integrati che ChatMaxima risolve automaticamente in fase di esecuzione. Ti danno accesso alle informazioni sul contatto, sulla conversazione, sul messaggio, sulla piattaforma e sui media correnti senza alcuna configurazione. Ogni Variabile Globale inizia con il prefisso sys_ ed è racchiusa tra parentesi graffe singole, come {sys_account_contact_name}.

Usa le Variabili Globali ovunque tu abbia bisogno di personalizzare contenuti, instradare conversazioni o passare contesto nelle integrazioni: blocchi del bot builder, modelli di broadcast, risposte automatiche, modelli di messaggio e payload di API o webhook.

Come Inserire una Variabile Globale

In qualsiasi campo di input supportato, basta digitare { e appare un selettore che elenca ogni Variabile Globale e Attributo Personalizzato disponibile. Seleziona quello che vuoi e ChatMaxima lo inserisce nel formato corretto.

Fai clic nel campo in cui vuoi inserire la variabile
Digita una singola parentesi graffa di apertura {
Scegli la variabile dal menu a tendina che appare
Il selettore inserisce il token completo, ad esempio {sys_account_contact_name}

Nota: I nomi delle variabili distinguono tra maiuscole e minuscole. Usa sempre parentesi graffe singole attorno al nome della variabile.

Variabili Globali Supportate

Variable	Description
`{sys_account_contact_name}`	Nome del contatto associato alla sessione del chatbot
`{sys_account_contact_email}`	Indirizzo email del contatto che interagisce con il chatbot
`{sys_account_contact_mobile}`	Numero di cellulare associato all'account del contatto
`{sys_contact_reference_id}`	Id di riferimento per la conversazione corrente
`{sys_current_message}`	Messaggio corrente in fase di elaborazione in un bot
`{sys_account_platform}`	Piattaforma corrente elaborata in un bot (ad esempio, WhatsApp, Facebook, Telegram)
`{sys_current_date_time}`	Data e ora correnti al momento dell'esecuzione
`{sys_current_page_url}`	URL della pagina web in cui il chatbot è attualmente attivo
`{sys_current_conversation}`	Cronologia completa della conversazione, inclusi messaggi e timestamp
`{sys_ai_intent}`	Intento rilevato dalla query dell'utente nei blocchi MaxIA (ad esempio, `general_query`, `human_agent`, `booking_request`)
`{sys_current_media}`	URL, tipo e nome file del media più recente (immagine, video, audio, documento) caricato dall'utente, come oggetto JSON. Usa `{sys_current_media.url}` o `{sys_current_media.type}` per campi specifici

Variabili di Contatto

Queste si risolvono nei dati memorizzati nel profilo del contatto.

{sys_account_contact_name} è la variabile più comune per la personalizzazione. Usala nei saluti, nei modelli di broadcast e nei messaggi di conferma.
{sys_account_contact_email} e {sys_account_contact_mobile} sono utili per passare l'identità in webhook, sincronizzazione CRM e flussi di verifica.
{sys_contact_reference_id} identifica in modo univoco il thread della conversazione, utile per correlare eventi tra sistemi diversi.

Variabili di Conversazione

Queste descrivono il messaggio corrente e la cronologia.

{sys_current_message} contiene il testo che l'utente ha appena inviato. Usala per restituire l'input, registrarlo o passarlo a un blocco API.
{sys_current_conversation} contiene la cronologia completa della chat con timestamp, utile per la sintesi AI o per il contesto di trasferimento.

Variabili di Canale e Contesto

{sys_account_platform} ti permette di diramare la logica per canale, ad esempio inviando un messaggio diverso su WhatsApp rispetto al Widget Web.
{sys_current_page_url} cattura il punto del tuo sito in cui si trovava il visitatore quando ha iniziato a chattare. Utile per l'instradamento o le analitiche.
{sys_current_date_time} marca il momento dell'esecuzione, utile per i timestamp nei ticket o nei sistemi a valle.

Variabili AI e Media

{sys_ai_intent} viene popolata dai blocchi MaxIA dopo il rilevamento dell'intento. Dirama il tuo bot in base al fatto che l'utente voglia human_agent, booking_request, general_query e così via.
{sys_current_media} è un oggetto JSON che descrive il file più recente inviato dall'utente. Accedi ai singoli campi con la notazione a punti:

{sys_current_media.url}
{sys_current_media.type}
{sys_current_media.filename}

Variabili Globali vs Attributi Personalizzati

ChatMaxima supporta due tipi di segnaposto dinamici. Entrambi appaiono nello stesso selettore {.

	Variabili Globali	Attributi Personalizzati
Prefisso	`sys_`	Nessuno (scegli tu il nome)
Creato da	ChatMaxima (integrato)	Tu, nelle impostazioni Contatti
Esempi	`{sys_account_contact_name}`, `{sys_current_message}`	`{company_name}`, `{order_id}`, `{plan_type}`
Origine del valore	Sessione, profilo del contatto, messaggio o contesto della piattaforma	Memorizzato su ciascun contatto, popolato manualmente, tramite importazione CSV, blocco bot o API
Usa quando	Il dato è qualcosa che ChatMaxima già conosce	Il dato è specifico per la logica del tuo business

Dove Usare le Variabili Globali

Le Variabili Globali funzionano in tutta la piattaforma ovunque sia disponibile il selettore {:

Blocchi del Bot Builder: Invia Messaggio, Invia Email, Blocco API, Blocco Webhook, Blocco Condizionale, Blocco Imposta Attributo e la maggior parte degli altri blocchi accettano variabili nei loro campi di testo e parametro.
Modelli di broadcast: Mappa i segnaposto dei modelli WhatsApp approvati ({{1}}, {{2}}) alle Variabili Globali quando crei un broadcast.
Risposte automatiche e risposte predefinite: Personalizza i messaggi di assenza e le risposte salvate.
Prompt AI della Knowledge Base: Passa il contesto della sessione nel prompt di sistema del tuo agente AI.
Webhook e integrazioni: Includi variabili negli URL dei webhook, nelle intestazioni e nei corpi delle richieste per inoltrare il contesto a sistemi esterni.

Esempi di Casi d'Uso

Personalizzare un broadcast WhatsApp

Modello approvato:

Hello {{1}}, your order {{2}} has been confirmed.

Nel compositore di broadcast, mappa {{1}} a {sys_account_contact_name} e {{2}} al tuo attributo personalizzato {order_id}. Ogni destinatario riceve un messaggio come "Hello Priya, your order ORD-1042 has been confirmed."

Salutare per nome in un bot

Inserisci un blocco Invia Messaggio all'inizio del tuo flusso con:

Hi {sys_account_contact_name}, how can we help you today?

Se il contatto non ha un nome registrato, il segnaposto si risolve in vuoto, quindi aggiungi un ramo di fallback quando necessario.

Instradare in base all'intento AI

Usa {sys_ai_intent} in un Blocco Condizionale dopo un blocco MaxIA:

Se {sys_ai_intent} è uguale a human_agent, instrada verso la chat dal vivo
Se {sys_ai_intent} è uguale a booking_request, salta al tuo flusso di prenotazione
Altrimenti, continua con il flusso FAQ

Passare il contesto in un webhook

Nel corpo di un Blocco Webhook:

{
  "name": "{sys_account_contact_name}",
  "phone": "{sys_account_contact_mobile}",
  "message": "{sys_current_message}",
  "platform": "{sys_account_platform}",
  "page": "{sys_current_page_url}"
}

ChatMaxima sostituisce ogni variabile con il valore reale prima di inviare la richiesta.

Inoltrare un file caricato al tuo backend

Se un utente invia un'immagine e devi salvarla lato server, usa:

{
  "file_url": "{sys_current_media.url}",
  "file_type": "{sys_current_media.type}",
  "file_name": "{sys_current_media.filename}"
}

Buone Pratiche

Convalida i dati dei tuoi contatti: Se una Variabile Globale come {sys_account_contact_mobile} manca per un contatto, il segnaposto si risolve in vuoto. Pulisci i dati dei tuoi contatti prima di inviare un broadcast.
Combina con gli Attributi Personalizzati: Usa le Variabili Globali per i dati di identità e sessione, e gli Attributi Personalizzati per campi specifici del business come numeri d'ordine, tipi di piano o date di appuntamento.
Testa prima di inviare: Esegui un broadcast o una sessione bot di prova sul tuo record di contatto per confermare che ogni variabile si risolva correttamente.
Usa la notazione a punti per le variabili JSON: {sys_current_media} restituisce un oggetto JSON. Accedi sempre a campi specifici come {sys_current_media.url} invece di usare l'intero oggetto in testo semplice.
Evita di codificare valori fissi: Ovunque scriveresti altrimenti il nome, il cellulare o l'email di un contatto, usa invece una Variabile Globale.

Risoluzione dei Problemi

La variabile appare come testo letterale nell'output

Verifica che la variabile sia racchiusa tra parentesi graffe singole, non doppie: {sys_account_contact_name} è corretto, {{sys_account_contact_name}} no (le parentesi doppie sono la sintassi dei segnaposto dei modelli Meta, usata solo all'interno dei modelli WhatsApp approvati).
Conferma che l'ortografia corrisponda esattamente a quella del selettore. Le variabili distinguono tra maiuscole e minuscole.
Assicurati di usare la variabile in un campo supportato. Alcuni campi di testo semplice al di fuori degli editor di bot, broadcast e modelli non analizzano le variabili.

La variabile si risolve in vuoto

Verifica che i dati sottostanti esistano nel profilo del contatto (ad esempio, che il contatto abbia effettivamente un nome o un cellulare salvato).
Per {sys_ai_intent}, conferma che un blocco MaxIA sia stato eseguito prima del punto in cui viene usata la variabile.
Per {sys_current_media}, conferma che l'utente abbia inviato media in questa sessione.

Hai bisogno di un valore che ChatMaxima non espone

Se il valore di cui hai bisogno non è nell'elenco delle Variabili Globali, crea un Attributo Personalizzato e popolalo tramite il profilo del contatto, un'importazione CSV, una chiamata API o un blocco bot Imposta Attributo.