Que variáveis Twig estão disponíveis na Nonli?

Os modelos Smart Message são escritos em Twig 3. Esta página lista todas as variáveis, funções e filtros que a Nonli suporta nesse contexto, com o respetivo tipo, os casos em que podem faltar e um exemplo testado. Para criar um modelo passo a passo, comece por Como criar um Smart Message.

1. Onde se aplica este contexto#

O mesmo contexto está disponível em dois locais:

• Modelos Smart Message, usados pelos bots, pelo botão em forma de lâmpada do editor de publicações e pelo botão do primeiro comentário. Podem preencher a mensagem, o título, a descrição, o comentário, o título do vídeo, o texto alternativo e o título da âncora do TikTok.
• Valores dinâmicos do Smart Image, quando um texto ou uma cor do Smart Image usa um modelo Smart Message como origem. Nesse caso, a variável context é igual a 'smart_image'. Consulte Como usar cores dinâmicas no Smart Image.

Os parâmetros de URL dinâmicos e o paywall dinâmico também usam Twig, mas com um contexto muito mais reduzido: um post restrito (source, social_account, post_type, author, user_id, breaking_news, short_id), referer, a função isComment(), e contadores e percentis. organic, os aliases de primeiro nível e as funções Smart Message indicadas abaixo não existem nesse contexto.

2. Regras de nomes e de tipos#

• Prefira os caminhos completos. Escreva organic.title ou post.social_account.type em vez de um alias de primeiro nível. Os aliases continuam a ser suportados nos modelos existentes.
• Os nomes estão em snake_case e seguem os nomes dos campos armazenados: canonical_url, published_at, open_graph.
• Respeite o singular e o plural. Os caminhos são organic.category, organic.tag, organic.author; os aliases são tags e authors. Um nome errado como categories, organic.categories, tag ou author não gera um erro: produz um valor vazio.
• Tipos. Uma string é um texto. Uma list é uma sequência de valores: teste-a com in, leia-a com |first ou |join(', '), e nunca a imprima diretamente. Um object agrupa outros caminhos. Seguem-se os números, os booleanos e as datas. As datas são strings ISO 8601 em UTC, como 2026-10-18T07:30:00.000Z; formate-as com |date.
• Ausência. Um valor só existe quando a origem o fornece. Depende da origem da publicação (artigo, publicação manual, publicação sem link), da rede social, do tipo de publicação e dos metadados que o scraper encontrou na página. Um caminho organic em falta produz um valor vazio; uma lista vazia é tratada como em falta.

Use ?? para substituir um valor em falta ou null, e ?: ou |default() para substituir também uma string vazia:

Depois de um filtro, use ?: ou |default(), nunca ??: {{ x|upper ?? 'B' }} é um erro de sintaxe, e o modelo é recusado quando o guarda.

3. Variáveis de primeiro nível#

Estas variáveis estão sempre definidas num Smart Message.

3.1. Aliases legados#

Quando a publicação provém de um artigo, a Nonli também copia alguns campos do artigo para o primeiro nível. Estes aliases ficam definidos (eventualmente null) assim que existe um artigo, e não definidos quando a publicação não tem nenhum. Cada um tem um caminho completo preferido.

Num artigo real, title e title1 contêm muitas vezes o mesmo título, head_title contém o título SEO mais longo e meta_description começa muitas vezes pela entrada. Qualquer um deles pode estar vazio, por isso preveja sempre uma alternativa.

As opções «Meta custom …» do editor e das origens dos bots correspondem a estes aliases meta_custom_*. Só são preenchidas nos sites para os quais a Nonli configurou uma regra de extração dedicada. Um artigo de um site exterior à sua empresa expõe apenas os seus campos públicos, pelo que organic.counter.view está em falta nesse caso.

4. [object Object],: o artigo de origem#

organic existe quando a publicação provém de um artigo (bot, URL colado no editor, SDK, RSS). Uma publicação manual ou uma publicação sem link não tem artigo: organic é então uma lista vazia e todos os caminhos organic.* ficam vazios.

4.1. Categorias e ,[object Object]#

A Nonli armazena o valor articleSection do JSON-LD, e os outros sinais de categoria da página, em organic.category. É uma lista, não um texto, e não existe nenhuma variável categories. Os valores são normalizados: minúsculas, acentos removidos, pontuação transformada em espaços. Por exemplo, Politique & Société, Économie e Sports > Rugby passam a politique societe, economie e sports rugby. Compare sempre com os valores efetivamente observados nos seus próprios artigos.

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

Primeira categoria, ou nada: {{ organic.category|default([])|first|default('') }}

Todas as categorias: {{ organic.category|default([])|join(', ') }}

A secção Open Graph em bruto, não normalizada, continua disponível como {{ organic.meta.open_graph.article.section ?? '' }}.

5. [object Object],: a publicação#

post descreve a publicação em criação ou em edição. Os campos são preenchidos progressivamente: um campo que está a ser gerado continua vazio enquanto o seu próprio modelo é produzido.

Os identificadores internos e os campos técnicos (ID de utilizador, de empresa e de marca, e-mail da conta, URL do webhook, estados, rastos de erro, contadores em bruto) estão deliberadamente excluídos: não constituem uma interface pública estável e não devem aparecer em textos publicados. post.user_id só está documentado para os parâmetros de URL.

6. Contadores e percentis#

Um contador só é carregado quando o modelo o nomeia explicitamente, por exemplo post.counter.click. Fica em falta quando a métrica ainda não existe, o que acontece sempre numa publicação que ainda não foi publicada. Escreva sempre uma alternativa: {{ post.counter.click ?? 0 }}.

Uma variável de percentil compara uma publicação com as publicações feitas pela mesma conta durante um período, excluindo as notícias de última hora. O seu nome é percentile + percentil (1 ou 2 algarismos) + métrica + duração (1 ou 2 algarismos) + unidade:

• métricas: Click, Engagement, Reach, VideoViews, Ctr, Overperforming, Monetization;
• unidades: h hora, d dia, w semana, m mês, y ano.

percentile50Click1d é a mediana dos cliques em 1 dia; percentile90Engagement7d é o 90.º percentil do envolvimento em 7 dias. O valor é null sem dados e fica em cache durante 30 minutos.

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

7. Funções#

aiGenerated() só resolve nomes de primeiro nível indicados como texto. Passe 'description' ou o próprio valor (organic.title), nunca o texto 'organic.title', que é devolvido literalmente. Um nome que não existe também é devolvido literalmente: numa publicação sem artigo, aiGenerated('description', …) devolve a palavra description. Proteja-a com uma condição:

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

8. Filtros#

Os filtros e operadores Twig padrão (default, first, join, length, trim, replace, date, map, in, ??, ?:, ~) estão documentados na documentação do Twig. A Nonli acrescenta ou substitui os filtros seguintes. Todos os resultados abaixo provêm do motor de renderização da Nonli.

Regras que evitam erros de renderização:

• extractMatch e pregReplace falham quando o valor é null. Acrescente |default('') antes deles: {{ meta_custom_publisher|default('')|extractMatch('/^(.+?[.!?…])(?=[[:space:]]|$)/u') }}.
• encode não protege &, = nem #: não o use para construir um parâmetro a partir de um valor que os possa conter.
• Prefira as classes POSIX como [[:digit:]], [[:space:]] e [[:alpha:]] às sequências com barra invertida: resistem ao copiar e colar. Copie os modelos de um bloco de código, nunca de uma linha apresentada num chat ou num e-mail, que pode perder as barras invertidas.

9. Receitas testadas#

Todas as receitas abaixo foram produzidas com o motor Twig da Nonli em conjuntos de teste de artigos completos, parciais e vazios.

Título (H1 ou title) seguido da meta description, com um link curto apenas onde é necessário. Numa publicação com link no Facebook, devolve o título e a descrição; numa fotografia no Facebook, acrescenta ➡️ [SHORTLINK]; no Instagram, nunca acrescenta um link; sem artigo, devolve um texto vazio.

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 -%}

Primeira frase da descrição, depois a descrição, depois o título.

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

Primeira frase do campo publisher personalizado, recorrendo ao texto alternativo da imagem e, depois, ao título.

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

Texto por rede e por tipo de publicação.

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

Cor do Smart Image por categoria. Devolve #E50032 para política, #16A34A para desporto e #6F819D nos restantes casos.

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

Valores de rastreio a partir da conta de destino.

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

Data de publicação no fuso horário da redação. 2026-10-18T07:30:00.000Z passa a 18/10/2026 09:30. Sem data de publicação, date imprimiria a data atual, por isso a condição deixa, em vez disso, o texto vazio.

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

Hashtags a partir das etiquetas. ['budget', 'impots'] passa a #Budget #Impots.

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

Manter as palavras curtas e os números junto da palavra seguinte (para os títulos do Smart Image, que nunca mudam de linha num espaço inseparável). La finale se jouera à guichets fermés mantém La, se e à ligados à palavra seguinte, e 16 septembre ou 3 000 euros ficam juntos. A alteração aplica-se apenas às imagens geradas a partir de agora.

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

O Twig transforma \xC2\xA0 num espaço inseparável; $1 mantém a palavra curta ou o número encontrado.

10. Campos inteligentes automáticos e ao clique#

Cada marca tem duas definições: Automatic configuration of smart fields (configuração automática dos campos inteligentes) e Smart field configuration at the click of the button (configuração dos campos inteligentes ao clique do botão). O botão do editor usa a configuração ao clique e só recorre à automática quando não existe nenhuma configuração ao clique. Um campo definido com o modelo público Empty é esvaziado quando clica no botão, porque o editor escreve de novo o valor gerado no campo.

Os bots não usam estas definições da marca. Cada bot tem as suas próprias origens, como Message's source e Description's source, que apontam para um valor incorporado (Title, Description, e assim por diante) ou para um modelo Smart Message.

11. Resolução de problemas#

11.1. O meu bot consulta a sua origem, mas não cria nenhuma publicação#

Um bot ativo pode encontrar o artigo e, ainda assim, não criar nenhuma publicação quando o seu Smart Message produz uma mensagem vazia. Isto acontece, por exemplo, quando o modelo lê um campo opcional como meta_custom_publisher e o artigo não o tem. A Nonli filtra então o candidato antes de qualquer publicação: uma mensagem vazia, ou com cinco caracteres ou menos depois de removido o link curto, é descartada, tal como uma publicação com link e título vazio. A verificação da mensagem vazia não se aplica aos bots definidos como No message nem ao Pinterest; a verificação do título vazio aplica-se a todos os bots.

Isto é diferente de uma publicação que foi criada e depois falhou na rede: essa publicação está visível em Posts com um estado de erro. Consulte Porque é que o meu bot não publicou este artigo? para identificar primeiro a etapa.

1. Compare. Identifique o bot exato. Compare algumas mensagens que gerou com êxito anteriormente com os metadados dos artigos correspondentes, e verifique o que mudou na sua configuração. O nome de um modelo ou o HTML atual da página não provam, por si só, o que funcionava antes. Teste a renderização do modelo atual num artigo elegível representativo e verifique se a variável está em falta ou presente, mas vazia.

2. Corrija. Prefira restaurar a origem de mensagem anterior quando esta dava o texto pretendido, ou acrescente uma alternativa adequada ao tipo da variável:

   twigCopy

   1{{- meta_custom_publisher ?: title -}}

   Se o título do artigo corresponder ao texto pretendido, abra o bot, defina Message's source como Title e, depois, clique em Save. Isto altera o texto gerado.

   

   Excerto das definições do bot: Message's source definido como Title, antes de clicar em Save.

3. Âmbito. Alterar a origem do bot afeta apenas as publicações futuras desse bot. Editar um modelo Smart Message partilhado afeta todos os bots e campos que o usam. As publicações existentes nunca são reescritas.

4. Verifique. Aguarde a próxima consulta normal e observe os artigos que continuam elegíveis. Os artigos mais antigos não são recuperados automaticamente, e uma publicação manual não prova que o bot voltou a funcionar.

11.2. Antetítulo, entrada e primeira frase são valores diferentes#

Um marcador editorial curto (por vezes chamado antetítulo), a entrada completa e a primeira frase de um texto são três coisas diferentes. A Nonli não tem uma variável dedicada ao marcador curto: uma regra específica do site pode armazená-lo num campo meta_custom_*, e alguns artigos legitimamente não têm nenhum. Não substitua um marcador em falta pela entrada inteira. Mostre o marcador apenas quando existe:

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

Com um marcador, o resultado é EXCLUSIVE | Budget 2027: what changes; sem marcador, apenas o título. Aqui, meta_custom_instagram é apenas um exemplo: use o campo que a regra do seu site preenche efetivamente.

meta_description (meta description nativa), meta_custom_publisher (campo personalizado) e description (descrição escolhida pela Nonli) são entradas de dados distintas. Um modelo que lê uma delas não é afetado quando outra é corrigida. Atualizar um campo recolhido não altera a origem do bot selecionada, o texto do Smart Image nem as publicações já geradas.

11.3. Descrição recolhida completa ou primeira frase da entrada#

Há quatro valores que são frequentemente confundidos quando um bot compõe a sua mensagem:

• Descrição recolhida (description, organic.description): a descrição do artigo que a Nonli recolheu, usada tal como está, sem ser dividida em frases. A Nonli obtém-na primeiro dos dados estruturados do artigo; caso contrário, do Open Graph, depois do Twitter Card e, por fim, da meta description nativa. Quando provém destas tags, mantém o corte de 500 caracteres das mesmas. A descrição do item RSS (meta_custom_rss_description) nunca é usada como descrição recolhida.
• Metadados nativos (meta_description, og_description, twitter_description): as descrições declaradas nas meta tags da página. A Nonli corta cada uma delas a 500 caracteres quando as recolhe. Este limite é específico destes três campos: uma descrição recolhida obtida dos dados estruturados não é cortada.
• Primeira frase: um modelo como Template: [public] Message from first standfirst sentence mantém deliberadamente uma única frase e gere o link através do seu próprio marcador [SHORTLINK].
• Marcador curto: um campo opcional descrito na secção anterior, que alguns artigos não têm.

Nem o nome de um modelo nem a origem selecionada provam que a descrição recolhida é a sua entrada completa. Para publicar a descrição recolhida completa em vez da sua primeira frase:

1. Verifique o que foi recolhido. Em alguns artigos representativos, compare description com a entrada completa que espera. Se estiver em falta, cortada ou contiver texto do corpo em vez da entrada, peça ao suporte que corrija e verifique primeiro a recolha. Alterar a origem do bot não pode recuperar um texto que não foi recolhido.
2. Altere a origem. Abra o bot, defina Message's source como Description e, depois, clique em Save. Não a confunda com Description's source, que preenche o campo de descrição da publicação, não o seu texto.
3. Verifique a mensagem seguinte. Observe a próxima publicação que o bot gerar: o texto completo, onde aparece o link e o limite de texto de cada rede de destino. Uma descrição completa pode ser longa, e escolhê-la não garante que todas as redes aceitem o texto inteiro. A Nonli continua a gerir o link curto: numa publicação sem link nativo, acrescenta o link curto logo a seguir ao texto gerado, antes de qualquer sufixo do bot e das hashtags, a menos que o primeiro comentário já o contenha. As publicações de link e de partilha não recebem nenhum link curto acrescentado, exceto as publicações com link no X e no Mastodon, onde é acrescentado mesmo no fim. As mensagens do Instagram e do TikTok não recebem nenhum link curto. Um modelo de primeira frase pode encurtar o texto ou colocar o link de forma diferente consoante a rede, por isso não espere o mesmo resultado.
4. Âmbito. A alteração aplica-se apenas às publicações que este bot gerar a partir de agora. As publicações existentes, os outros bots e os modelos Smart Message partilhados ficam inalterados, e nenhum artigo mais antigo é importado ou republicado.

11.4. Os apóstrofos estragam o meu modelo#

Numa string Twig entre plicas, um apóstrofo termina a string. Este modelo é recusado quando o guarda, com um erro como «Invalid template syntax at line 1»:

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

Faça o escape do apóstrofo, use um apóstrofo tipográfico ou use aspas duplas:

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

O número de linha indicado é a linha do modelo que contém o erro.

11.5. Uma variável continua vazia#

• Verifique a ortografia exata: organic.category, não categories; tags, não tag.
• Verifique se a publicação tem um artigo: organic está vazio nas publicações manuais e sem link, e os aliases ficam então não definidos.
• Imprima uma lista com |join(', ') ou teste-a com in.
• Compare as categorias com a sua forma normalizada (politique societe, não Politique & Société).
• Verifique os contadores com ?? 0: estão em falta antes da publicação.

11.6. Um modelo pode adicionar colaboradores no Instagram?#

Não. Os modelos preenchem apenas campos de texto, e airtable() devolve texto: pode escrever uma @menção, não criar uma colaboração. Adicione os colaboradores no editor de publicações com Collaborators, ou com o campo de API collaborator[] (slug, type) de POST ou PUT /v2.1/posts/bulk. A Meta aceita até 3 colaboradores; consulte Como fazer uma colaboração no Instagram com a Nonli.