Pular para o conteúdo principal
Liquid é uma linguagem de templating suportada pelo OneSignal para personalizar mensagens através de canais incluindo email, push, SMS, in-app e Live Activities. Ela usa tags, filtros e condicionais para personalizar dinamicamente o conteúdo da mensagem. Para aprender mais sobre sintaxe Liquid, veja a documentação oficial do Liquid.

​
Campos suportados por tipo de mensagem

  • Email
  • Push
  • SMS
  • In-App Messages
  • Live Activities
  • Subject, Reply-to e Pre-header
  • Message Body
  • Substituição de imagem em blocos HTML. Exemplo: <img src="{{image_url}}"/>
  • Ações de bloco de botão como URLs, Mail to e outros campos.

​
Sintaxe básica

Liquid usa duas estruturas de sintaxe principais:
  1. Output Tags: {{ ... }} - Exibem dados de uma variável ou objeto.
  2. Logic Tags: {% ... %} - Executam instruções condicionais ou loops.

​
Fontes de dados

SourceExampleDescription
Tag{{ first_name }}SDK OneSignal ou API (tags)
Property{{ subscription.email }}Gerenciado pelo sistema (email, external_id, language, etc.)
Journey Name{{ journey.name }}Gerenciado pelo sistema
Custom Data{{ message.custom_data.key }}custom_data passado na API Create Message
Data Feeds{{ data_feed.cart.size }}Data Feeds permitem que você puxe dados em tempo real de suas APIs diretamente nas mensagens no momento do envio.
Custom Events{{ journey.last_event.name }}Definido via Event Triggered Journeys, nós Wait Until

​
Condicionais

​
Operadores

  • ==, !=, >, <, >=, <=
  • and, or
  • contains (string ou array)
Operações executam da direita para esquerda. Parênteses não são suportados.
liquid
{% if true or false and false %}
  This is true.
{% endif %}

​
if, elsif, else

liquid
{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}

​
unless

liquid
{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}

​
Filtros

Aplique filtros usando {{ variable | filter }} para ajustar como os dados são exibidos.

​
default

Atribua um valor padrão se a propriedade estiver vazia ou não existir.
liquid
Hello {{ first_name | default: "there" }}.

​
date

O filtro date converte um timestamp em outro formato de data. O formato para esta sintaxe é o mesmo que strftime. A entrada usa o mesmo formato que Ruby’s Time.parse. Defina datas como um timestamp unix em segundos com tags. Isso permite o uso tanto de personalização de sintaxe Liquid quanto de segmentação com Time Operators. Por exemplo, uma tag pode parecer com: bill_due : 1687968776
liquid
{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}
Result
Wed, Jun 28, 23
liquid
{{ bill_due | date: "%Y" }}
Result
2023
Formatação de data funciona em strings se elas contiverem datas bem formatadas.
liquid
{{ "March 14, 2016" | date: "%b %d, %y" }}
Result
Mar 14, 16
Para obter a hora atual, passe a palavra especial now (ou today) junto com o filtro date.
liquid
This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
Result
This message was sent at 2022-11-02 14:39.
A hora atual será renderizada na mensagem com base em quando a mensagem é enviada ao destinatário. Se você estiver testando a mensagem, você verá a hora atual como quando a mensagem de teste foi enviada.

​
capitalize

Este filtro torna a primeira letra de uma string maiúscula e converte os caracteres restantes em minúsculas.
liquid
{{ "my GREAT title" | capitalize }}
Result
My great title

​
round

Este filtro arredonda um número para o inteiro mais próximo, ou, se um número for passado como argumento, para aquele número de casas decimais.
liquid
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
Result
1
3
183.36

​
pluralize

Este filtro retorna a forma singular ou plural de uma string com base em um número fornecido. O número deve ser um número inteiro e pode ser fornecido como uma string. As formas singular e plural de uma string devem ser fornecidas.
liquid
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
Result
singular
plural
1 person
2 people
2 people

​
Iteração

​
Loops for

Executa repetidamente um bloco de código. Para uma lista completa de atributos disponíveis dentro de um loop for, consulte o objeto de loop for.
liquid
{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    Sorry, we're sold out of all products.
  {% endfor %}
Request Body
{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
    "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c",
    "custom_data": {
      "products": [
        { "name": "Sweater" },
        { "name": "Hat" },
        { "name": "Shirt" }
      ]
    }
  }
Results
  - Sweater
  - Hat
  - Shirt

  // if message.custom_data.products is empty
  Sorry we're sold out of all products
Embora poderoso e flexível, o uso de loops for em sintaxe Liquid pode levar a baixo desempenho de entrega de notificações em certos casos raros. Seja consciente do seu uso de loops for. Também note que prevenimos o uso de loops for em alguns campos do canal Push: contents, headings, subtitle, apns_alert e url

​
limit & offset

Limita o loop ao número especificado de iterações. Por exemplo, se você deseja apenas mostrar 4 produtos em uma mensagem, você pode usar Limits e Offsets para especificar o número de produtos mostrados.
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
Result
1 2
Para iniciar o loop no índice especificado, adicione um valor de offset:
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}
```text Result
1 2 3
4 5 6

​
where

Cria um array incluindo apenas os objetos com um valor de propriedade fornecido, ou qualquer valor verdadeiro por padrão. Neste exemplo, assuma que você tem uma lista de produtos e deseja mostrar seus produtos de cozinha separadamente. Usando where, você pode criar um array contendo apenas os produtos que têm um type de kitchen.
Data
products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]
liquid
All products:
{% for product in products %}
- {{ product.name }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}
Result
All products:
  - Vacuum
  - Spatula
  - Television
  - Garlic press

Kitchen products:
- Spatula
- Garlic press

​
Manipulação de String

Ocasionalmente você pode ter tags de dados que contêm strings em um formato que não é adequado para ser mostrado diretamente aos seus usuários, e você pode precisar manipular a string para ajustar o formato. Abaixo está uma tabela de comandos de sintaxe Liquid que podem ser usados para ajustar strings. Você pode usar manipulação de string tanto em Tags quanto diretamente em strings escritas na mensagem.
CommandDescriptionExampleExample Output
replaceSubstitui uma substring por outra string.{{ 'hello world' | replace: 'world', 'there' }}hello there
capitalizeTorna a primeira letra de uma string maiúscula.{{ 'hello' | capitalize }}Hello
upcaseConverte uma string para maiúsculas.{{ 'hello' | upcase }}HELLO
downcaseConverte uma string para minúsculas.{{ 'HELLO' | downcase }}hello
stripRemove espaços em branco à esquerda e à direita de uma string.{{ ' hello ' | strip }}hello
strip_htmlRemove todas as tags HTML de uma string.{{ '<p>hello</p>' | strip_html }}hello
truncateEncurta uma string para um comprimento especificado, adicionando reticências (…) se necessário.{{ 'This is a long sentence' | truncate: 10 }}This is a…
truncatewordsTrunca uma string após um certo número de palavras.{{ 'This is a long sentence' | truncatewords: 2 }}This is…
replace_firstSubstitui a primeira ocorrência de uma substring.{{ 'hello world' | replace_first: 'world', 'there' }}hello there
prependAdiciona uma string ao início de outra string.{{ 'world' | prepend: 'hello ' }}hello world
appendAdiciona uma string ao final de outra string.{{ 'hello' | append: ' world' }}hello world
lstripRemove espaços em branco à esquerda de uma string.{{ ' hello' | lstrip }}hello
rstripRemove espaços em branco à direita de uma string.{{ 'hello ' | rstrip }}hello

​
FAQ

​
Por que a substituição não está funcionando?

  • Mensagens in-app não suportam substituição de propriedade.
  • Substituição de tag não funciona ao usar “Send Test Message”.
  • Chaves de tag devem ser alfanuméricas, ou usar _ e - (sem pontos ou espaços).
  • Substituição não aparece em modo preview — envie uma mensagem real para testar.

​
Como controlar espaços em branco e quebras de linha?

Use hífens: {{- ... -}}, {%- ... -%} para remover espaços em branco ao redor. Veja Controle de espaços em branco para mais detalhes.

​
Como lidar com conteúdo gerado por usuários?

Envolva texto gerado por usuários em {% raw %} e {% endraw %} para prevenir análise Liquid. Veja sintaxe “raw”.
json
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}