Quali variabili Twig sono disponibili in Nonli?

I template Smart Message sono scritti in Twig 3. Questa pagina elenca tutte le variabili, funzioni e filtri che Nonli supporta in questo contesto, con il relativo tipo, i casi in cui possono mancare e un esempio testato. Per creare un template passo dopo passo, parti da Come creare uno Smart Message.

1. Dove si applica questo contesto#

Lo stesso contesto è disponibile in due punti:

• Template Smart Message, usati dai bot, dal pulsante a forma di lampadina dell'editor dei post e dal pulsante del primo commento. Possono compilare messaggio, titolo, descrizione, commento, titolo del video, testo alternativo e titolo dell'ancora TikTok.
• Valori dinamici di Smart Image, quando un testo o un colore di Smart Image usa un template Smart Message come sorgente. In questo caso la variabile context è uguale a 'smart_image'. Vedi Come usare i colori dinamici in Smart Image.

Anche i parametri URL dinamici e il paywall dinamico usano Twig, ma con un contesto molto più ridotto: un post limitato (source, social_account, post_type, author, user_id, breaking_news, short_id), referer, la funzione isComment(), e contatori e percentili. organic, gli alias di primo livello e le funzioni Smart Message riportate di seguito non esistono in quel contesto.

2. Regole su nomi e tipi#

• Preferisci i percorsi completi. Scrivi organic.title o post.social_account.type anziché un alias di primo livello. Gli alias restano supportati per i template esistenti.
• I nomi sono in snake_case e seguono i nomi dei campi memorizzati: canonical_url, published_at, open_graph.
• Rispetta singolare e plurale. I percorsi sono organic.category, organic.tag, organic.author; gli alias sono tags e authors. Un nome errato come categories, organic.categories, tag o author non genera un errore: produce un valore vuoto.
• Tipi. Una string è un testo. Una list è una sequenza di valori: verificala con in, leggila con |first o |join(', '), non stamparla mai direttamente. Un object raggruppa altri percorsi. Seguono numeri, booleani e date. Le date sono stringhe ISO 8601 in UTC come 2026-10-18T07:30:00.000Z; formattale con |date.
• Assenza. Un valore esiste solo se la sorgente lo fornisce. Dipende dall'origine del post (articolo, post manuale, post senza link), dal social network, dal tipo di post e dai metadati che lo scraper ha trovato nella pagina. Un percorso organic mancante restituisce un valore vuoto; una lista vuota è considerata mancante.

Usa ?? per sostituire un valore mancante o null, e ?: o |default() per sostituire anche una stringa vuota:

Dopo un filtro usa ?: o |default(), mai ??: {{ x|upper ?? 'B' }} è un errore di sintassi e il template viene rifiutato quando lo salvi.

3. Variabili di primo livello#

Queste variabili sono sempre definite in uno Smart Message.

3.1. Alias legacy#

Quando il post proviene da un articolo, Nonli copia anche alcuni campi dell'articolo al primo livello. Questi alias sono definiti (eventualmente null) non appena esiste un articolo e non definiti quando il post non ne ha. Ognuno ha un percorso completo preferito.

In un articolo reale, title e title1 contengono spesso lo stesso titolo, head_title contiene il titolo SEO più lungo e meta_description inizia spesso con il sommario. Ognuno di essi può essere vuoto, quindi prevedi sempre un'alternativa.

Le scelte «Meta custom …» dell'editor e delle sorgenti dei bot corrispondono a questi alias meta_custom_*. Vengono compilate solo sui siti per cui Nonli ha configurato una regola di estrazione dedicata. Un articolo di un sito esterno alla tua azienda espone solo i suoi campi pubblici, quindi organic.counter.view non è disponibile.

4. [object Object],: l'articolo sorgente#

organic esiste quando il post proviene da un articolo (bot, URL incollato nell'editor, SDK, RSS). Un post manuale o un post senza link non ha un articolo: organic è allora una lista vuota e ogni percorso organic.* è vuoto.

4.1. Categorie e ,[object Object]#

Nonli memorizza il valore articleSection di JSON-LD, e gli altri segnali di categoria della pagina, in organic.category. È una lista, non un testo, e non esiste alcuna variabile categories. I valori sono normalizzati: minuscolo, accenti rimossi, punteggiatura trasformata in spazi. Ad esempio Politique & Société, Économie e Sports > Rugby diventano politique societe, economie e sports rugby. Confronta sempre con i valori effettivamente osservati sui tuoi articoli.

1{%- set categories = organic.category ?? [] -%}
2{%- if 'politique' in categories -%}
3Politics
4{%- endif -%}

Prima categoria, oppure nulla: {{ organic.category|default([])|first|default('') }}

Tutte le categorie: {{ organic.category|default([])|join(', ') }}

La sezione Open Graph originale, non normalizzata, resta disponibile come {{ organic.meta.open_graph.article.section ?? '' }}.

5. [object Object],: il post#

post descrive il post in fase di creazione o modifica. I campi vengono compilati progressivamente: un campo in corso di generazione è ancora vuoto mentre viene elaborato il suo template.

Gli identificativi interni e i campi tecnici (ID di utente, azienda e brand, email dell'account, URL del webhook, stati, tracce di errore, contatori grezzi) sono volutamente esclusi: non sono un'interfaccia pubblica stabile e non devono comparire nei testi pubblicati. post.user_id è documentato solo per i parametri URL.

6. Contatori e percentili#

Un contatore viene caricato solo quando il template lo nomina esplicitamente, ad esempio post.counter.click. Non è disponibile quando la metrica non esiste ancora, cosa che accade sempre per un post non ancora pubblicato. Scrivi sempre un'alternativa: {{ post.counter.click ?? 0 }}.

Una variabile percentile confronta un post con i post pubblicati dallo stesso account in un periodo, esclusi i breaking news. Il suo nome è percentile + percentile (1 o 2 cifre) + metrica + durata (1 o 2 cifre) + unità:

• metriche: Click, Engagement, Reach, VideoViews, Ctr, Overperforming, Monetization;
• unità: h ora, d giorno, w settimana, m mese, y anno.

percentile50Click1d è la mediana dei clic in 1 giorno; percentile90Engagement7d è il 90° percentile dell'engagement in 7 giorni. Il valore è null in assenza di dati e viene memorizzato nella cache per 30 minuti.

1{%- if (post.counter.engagement ?? 0) > (percentile50Engagement7d ?? 0) -%}TOP{%- else -%}NORMAL{%- endif -%}

7. Funzioni#

aiGenerated() risolve solo i nomi di primo livello forniti come testo. Passa 'description' oppure il valore stesso (organic.title), mai il testo 'organic.title', che viene restituito letteralmente. Anche un nome inesistente viene restituito letteralmente: su un post senza articolo, aiGenerated('description', …) restituisce la parola description. Proteggila con una condizione:

1{%- if organic -%}
2{{- aiGenerated('description', null, null, 40, '…', true) -}}
3{%- endif -%}

8. Filtri#

I filtri e gli operatori Twig standard (default, first, join, length, trim, replace, date, map, in, ??, ?:, ~) sono documentati nella documentazione di Twig. Nonli aggiunge o sostituisce i filtri seguenti. Tutti i risultati riportati qui sotto provengono dal renderer di Nonli.

Regole per evitare errori di elaborazione:

• extractMatch e pregReplace falliscono quando il valore è null. Aggiungi |default('') prima di essi: {{ meta_custom_publisher|default('')|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') }}.
• encode non protegge &, = o #: non usarlo per costruire un parametro a partire da un valore che potrebbe contenerli.
• Preferisci le classi POSIX come [[:digit:]], [[:space:]] e [[:alpha:]] alle sequenze con barra rovesciata: sopravvivono al copia e incolla. Copia i template da un blocco di codice, mai da una riga renderizzata di una chat o di un'email, che potrebbe perdere le barre rovesciate.

9. Ricette testate#

Ogni ricetta qui sotto è stata elaborata con il motore Twig di Nonli su fixture di articoli complete, parziali e vuote.

Titolo (H1 o title) seguito dalla meta description, con un link breve solo dove serve. In un post con link su Facebook restituisce il titolo e la descrizione; in una foto su Facebook aggiunge ➡️ [SHORTLINK]; su Instagram non aggiunge mai un link; senza articolo restituisce un testo vuoto.

1{%- set titre = title1 ?: title -%}
2{%- set desc = meta_description ?: description -%}
3{{- titre -}}
4{%- if desc -%}{{- '\n\n' ~ desc -}}{%- endif -%}
5{%- if post_type != 'link' and social_network not in ['instagram', 'tiktok', 'pinterest'] and not hasFirstCommentShortlink() and hasLink() -%}
6{{- '\n\n' ~ shortlink_prefix -}}[SHORTLINK]
7{%- endif -%}

Prima frase della descrizione, poi la descrizione, poi il titolo.

1{%- set source = meta_description ?: description ?: '' -%}
2{{- source|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') ?: source ?: title -}}

Prima frase del campo publisher personalizzato, con ripiego sul testo alternativo dell'immagine, poi sul titolo.

1{{- meta_custom_publisher|default('')|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') ?: organic.image_alt|default('') ?: title -}}

Testo per rete e tipo di post.

1{%- if social_network == 'instagram' -%}
2{{- title -}}
3{%- elseif post_type == 'link' -%}
4{{- description ?: title -}}
5{%- else -%}
6{{- title -}}
7{%- endif -%}

Colore di Smart Image per categoria. Restituisce #E50032 per la politica, #16A34A per lo sport e #6F819D negli altri casi.

1{%- set categories = organic.category ?? [] -%}
2{%- if 'politique' in categories -%}#E50032
3{%- elseif 'sport' in categories -%}#16A34A
4{%- else -%}#6F819D
5{%- endif -%}

Valori di tracciamento dall'account di destinazione.

1utm_source={{ post.social_account.type|default('social') }}&utm_campaign={{ post.social_account.slug|default('')|encode }}

Data di pubblicazione nel fuso orario della redazione. 2026-10-18T07:30:00.000Z diventa 18/10/2026 09:30. Senza una data di pubblicazione, date stamperebbe la data corrente, quindi la condizione lascia invece il testo vuoto.

1{%- if organic.published_at|default(null) -%}
2{{- organic.published_at|date('d/m/Y H:i', 'Europe/Paris') -}}
3{%- endif -%}

Hashtag dai tag. ['budget', 'impots'] diventa #Budget #Impots.

1{{ tags|default([])|map(t => '#' ~ t|camel)|join(' ') }}

Mantieni le parole brevi e i numeri insieme alla parola successiva (per i titoli di Smart Image, che non vanno mai a capo su uno spazio unificatore). La finale se jouera à guichets fermés mantiene La, se e à attaccati alla parola seguente, e 16 septembre o 3 000 euros restano uniti. La modifica si applica solo alle immagini generate da ora in poi.

1{%- set titre = organic.title ?? title -%}
2{{- titre|pregReplace("/(?<=^|[[:space:]])([[:alpha:]]{1,2}|[[:digit:]]+)[[:space:]]+/u", "$1\xC2\xA0") -}}

Twig trasforma \xC2\xA0 in uno spazio unificatore; $1 mantiene la parola breve o il numero che ha trovato corrispondenza.

10. Campi smart automatici e al clic#

Ogni brand ha due impostazioni: Automatic configuration of smart fields (configurazione automatica dei campi smart) e Smart field configuration at the click of the button (configurazione dei campi smart al clic del pulsante). Il pulsante dell'editor usa la configurazione al clic e ricorre a quella automatica solo quando non esiste alcuna configurazione al clic. Un campo impostato sul template pubblico Empty viene svuotato quando clicchi il pulsante, perché l'editor riscrive nel campo il valore generato.

I bot non usano queste impostazioni del brand. Ogni bot ha le proprie sorgenti, come Message's source e Description's source, che puntano a un valore integrato (Title, Description e così via) oppure a un template Smart Message.

11. Risoluzione dei problemi#

11.1. Il mio bot interroga la sua sorgente ma non crea alcun post#

Un bot attivo può trovare l'articolo e non creare comunque alcun post quando il suo Smart Message produce un messaggio vuoto. Succede, ad esempio, quando il template legge un campo facoltativo come meta_custom_publisher e l'articolo non lo ha. Nonli scarta allora il candidato prima di qualsiasi pubblicazione: viene scartato un messaggio vuoto, o di cinque caratteri o meno una volta rimosso il link breve, così come un post con link e titolo vuoto. La verifica del messaggio vuoto non si applica ai bot impostati su No message né a Pinterest; la verifica del titolo vuoto si applica a tutti i bot.

È diverso da un post che è stato creato e poi è fallito sulla rete: un post di questo tipo è visibile in Posts con uno stato di errore. Vedi Perché il mio bot non ha pubblicato questo articolo? per individuare prima la fase.

1. Confronta. Individua il bot esatto. Confronta alcuni messaggi che ha generato correttamente in passato con i metadati degli articoli corrispondenti e controlla cosa è cambiato nella sua configurazione. Il nome di un template o l'HTML attuale della pagina non bastano da soli a dimostrare cosa funzionava prima. Elabora il template attuale su un articolo idoneo rappresentativo e verifica se la variabile è assente oppure presente ma vuota.

2. Correggi. Preferisci ripristinare la sorgente del messaggio precedente quando dava la formulazione desiderata, oppure aggiungi un'alternativa adatta al tipo di variabile:

   twigCopy

   1{{- meta_custom_publisher ?: title -}}

   Se il titolo dell'articolo corrisponde alla formulazione desiderata, apri il bot, imposta Message's source su Title, poi clicca Save. Questo modifica il testo generato.

   

   Estratto delle impostazioni del bot: Message's source impostato su Title, prima di cliccare Save.

3. Ambito. Cambiare la sorgente del bot riguarda solo i post futuri di quel bot. Modificare un template Smart Message condiviso riguarda ogni bot e ogni campo che lo usa. I post esistenti non vengono mai riscritti.

4. Verifica. Attendi la prossima interrogazione normale e controlla gli articoli ancora idonei. Gli articoli più vecchi non vengono recuperati automaticamente, e un post manuale non dimostra che il bot si sia ripreso.

11.2. Occhiello, sommario e prima frase sono valori diversi#

Un breve marcatore editoriale (a volte chiamato occhiello), il sommario completo e la prima frase di un testo sono tre cose diverse. Nonli non ha una variabile dedicata per il marcatore breve: una regola specifica del sito può memorizzarlo in un campo meta_custom_*, e alcuni articoli legittimamente non ne hanno. Non sostituire un marcatore mancante con l'intero sommario. Mostra il marcatore solo quando esiste:

1{%- set marker = meta_custom_instagram|default('')|trim -%}
2{%- if marker -%}{{- marker ~ ' | ' -}}{%- endif -%}
3{{- title -}}

Con un marcatore il risultato è EXCLUSIVE | Budget 2027: what changes; senza, solo il titolo. Qui meta_custom_instagram è solo un esempio: usa il campo che la regola del tuo sito compila effettivamente.

meta_description (meta description nativa), meta_custom_publisher (campo personalizzato) e description (descrizione scelta da Nonli) sono input distinti. Un template che ne legge uno non è influenzato quando un altro viene corretto. Aggiornare un campo raccolto non cambia la sorgente del bot selezionata, il testo di Smart Image né i post già generati.

11.3. Descrizione raccolta completa o prima frase del sommario#

Quattro valori vengono spesso confusi quando un bot compone il suo messaggio:

• Descrizione raccolta (description, organic.description): la descrizione dell'articolo raccolta da Nonli, usata così com'è, non suddivisa in frasi. Nonli la prende prima di tutto dai dati strutturati dell'articolo, altrimenti da Open Graph, poi da Twitter Card, poi dalla meta description nativa. Quando proviene da questi tag, mantiene il loro taglio a 500 caratteri. La descrizione dell'elemento RSS (meta_custom_rss_description) non viene mai usata come descrizione raccolta.
• Metadati nativi (meta_description, og_description, twitter_description): le descrizioni dichiarate nei meta tag della pagina. Nonli taglia ciascuna di esse a 500 caratteri quando le raccoglie. Questo limite è specifico di questi tre campi: una descrizione raccolta presa dai dati strutturati non viene tagliata.
• Prima frase: un template come Template: [public] Message from first standfirst sentence mantiene deliberatamente una sola frase e gestisce il link tramite il proprio marcatore [SHORTLINK].
• Marcatore breve: un campo facoltativo descritto nella sezione precedente, che alcuni articoli non hanno.

Né il nome di un template né la sorgente selezionata dimostrano che la descrizione raccolta sia il tuo sommario completo. Per pubblicare l'intera descrizione raccolta invece della sua prima frase:

1. Verifica cosa è stato raccolto. Su alcuni articoli rappresentativi, confronta description con il sommario completo che ti aspetti. Se manca, è troncata o contiene il testo dell'articolo invece del sommario, chiedi al supporto di correggere e verificare prima la raccolta. Cambiare la sorgente del bot non può recuperare un testo che non è stato raccolto.
2. Cambia la sorgente. Apri il bot, imposta Message's source su Description, poi clicca Save. Non confonderla con Description's source, che compila il campo descrizione del post, non il suo testo.
3. Controlla il messaggio successivo. Guarda il prossimo post generato dal bot: il testo completo, dove compare il link e il limite di testo di ogni rete di destinazione. Una descrizione completa può essere lunga, e sceglierla non garantisce che ogni rete accetti l'intero testo. Nonli gestisce comunque il link breve: su un post senza link nativo, lo aggiunge subito dopo il testo generato, prima di qualsiasi suffisso del bot e degli hashtag, a meno che il primo commento non lo contenga già. I post di tipo link e condivisione non ricevono alcun link breve aggiunto, tranne i post con link su X e Mastodon, dove viene aggiunto in fondo al testo. I messaggi di Instagram e TikTok non ricevono alcun link breve. Un template con la prima frase può accorciare il testo o collocare il link in modo diverso a seconda della rete, quindi non aspettarti lo stesso risultato.
4. Ambito. La modifica si applica solo ai post che questo bot genera da ora in poi. I post esistenti, gli altri bot e i template Smart Message condivisi restano invariati, e nessun articolo più vecchio viene importato o ripubblicato.

11.4. Gli apostrofi bloccano il mio template#

In una stringa Twig tra apici singoli, un apostrofo chiude la stringa. Questo template viene rifiutato quando lo salvi, con un errore come «Invalid template syntax at line 1»:

1{{ gpt('Summarize the article's main point') }}

Fai l'escape dell'apostrofo, usa un apostrofo tipografico oppure usa le virgolette doppie:

1{{ gpt('Summarize the article\'s main point') }}
2{{ gpt('Summarize the article’s main point') }}
3{{ gpt("Summarize the article's main point") }}

Il numero di riga indicato è la riga del template che contiene l'errore.

11.5. Una variabile resta vuota#

• Controlla l'ortografia esatta: organic.category, non categories; tags, non tag.
• Controlla che il post abbia un articolo: organic è vuoto per i post manuali e senza link, e gli alias non sono allora definiti.
• Stampa una lista con |join(', ') oppure verificala con in.
• Confronta le categorie con la loro forma normalizzata (politique societe, non Politique & Société).
• Controlla i contatori con ?? 0: non sono disponibili prima della pubblicazione.

11.6. Un template può aggiungere collaboratori su Instagram?#

No. I template compilano solo campi di testo, e airtable() restituisce testo: può scrivere una @menzione, non creare una collaborazione. Aggiungi i collaboratori nell'editor dei post con Collaborators, oppure con il campo API collaborator[] (slug, type) di POST o PUT /v2.1/posts/bulk. Meta accetta fino a 3 collaboratori; vedi Come fare una collaborazione su Instagram con Nonli.