Sostituzioni e formule

Le sostituzioni sono variabili nella forma {{...}} che vengono inserite nei testi dei messaggi, nei campi delle azioni e nei template dei pulsanti quando una reazione si attiva. Le sostituzioni non riconosciute vengono lasciate così come sono. Oltre alle variabili esistono le formule per i calcoli. Il pulsante «Sostituzioni» nell'editor del messaggio aiuta a inserire le variabili.

Dati del mittente

  • {{first_name}}, {{last_name}} — nome e cognome.
  • {{username}} — @username dell'utente.
  • {{user_id}} — ID Telegram numerico.

Dati dell'evento e della chat

  • {{text}} (alias {{received_message}}) — testo del messaggio in arrivo.
  • {{message_id}} (alias {{received_message_id}}) — ID del messaggio in arrivo.
  • {{chat_id}}, {{chat_title}} (alias {{chat_name}}) — la chat in cui è avvenuto l'evento.
  • {{topic_id}}, {{topic_url}} — topic (per i forum).

Data e ora

  • {{date}} — data (AAAA-MM-GG), {{time}} — ora (HH:MM), {{datetime}} — data e ora.
  • Formattazione: {{date:DD.MM.YYYY HH:mm}} — token YYYY, YY, MM, DD, HH, mm, ss.

Parametri dell'utente

  • {{param.chiave}} (alias {{params.chiave}} o {{recipient.chiave}}) — valore del parametro dell'iscritto. I parametri vengono popolati dalle azioni «Modifica parametri», «Salva messaggio» e dalle risposte nel dialogo.

Contesto di esecuzione (ctx)

  • {{ctx.chiave}} (alias {{context.chiave}}) — valori temporanei dell'esecuzione corrente: dati del webhook in arrivo, risultati delle azioni (richiesta web, query alla sorgente, AI), dati ripristinati dal pulsante (Carry), elementi del ciclo.
  • In un ciclo su lista, l'elemento è accessibile tramite il suo alias, ad esempio {{item.nome}}.

Formule

La costruzione {{= espressione}} valuta l'espressione direttamente nel testo. Lo stesso motore funziona nell'azione «Calcolo» e nelle condizioni della tabella decisionale. Nelle espressioni puoi fare riferimento a parametri e valori ctx per nome, utilizzare aritmetica, confronti, logica e decine di funzioni (con supporto anche dei nomi equivalenti in russo).

Esempio: {{= ROUND(param.total * 0.9) }} — sconto del 10% sull'importo dal parametro.

Sintassi completa ed elenco delle funzioni — nella sezione Formule.

HTML nelle sostituzioni

I messaggi vengono inviati con markup HTML. Affinché un valore sostituito non rompa il layout (ad esempio quando un nome utente contiene <), i valori sostituiti vengono escapati per impostazione predefinita: i caratteri HTML diventano testo sicuro. I tag che scrivi direttamente nel testo della reazione (<b>, <a>, …) restano intatti.

Se un valore contiene già markup pronto (ad esempio un annuncio salvato in un parametro con <b>...</b>) e vuoi inserirlo così com'è, anteponi & alla sostituzione:

  • {{& key}} — inserimento grezzo per le sostituzioni {{...}}.
  • {&user:key}, {&recipient:key}, {&global:key} — inserimento grezzo per le sostituzioni di namespace.

Il prefisso & disabilita l'escaping solo per quella singola sostituzione — sei tu a garantire l'affidabilità della fonte del valore. È meglio lasciare escapati i token controllati dall'iscritto ({{first_name}}, …).

Durante l'importazione di bot da altri costruttori, le sostituzioni di namespace {user:…}/{recipient:…}/{global:…} vengono migrate automaticamente alla forma grezza {&…} — contengono in genere valori con markup pronto, come funzionava nel costruttore di origine.

Note sul formato

Le sostituzioni {{...}} funzionano in testi, didascalie, body delle richieste e template dei pulsanti. Dai ai parametri e alle chiavi ctx nomi brevi e in caratteri latini (email, total, order_id) — sono più comodi da inserire.

Prossimi passi

  • Formule — sintassi del DSL ed elenco completo delle funzioni.
  • Messaggi e pulsanti — dove si usano le sostituzioni.
  • Azioni — le azioni che popolano parametri e ctx.
  • Raccolte e dati — archiviazione dei dati tra un'esecuzione e l'altra.