Saltar al contenido principal
Liquid es un lenguaje de plantillas soportado por OneSignal para personalizar mensajes a través de canales incluyendo email, push, SMS, in-app y Live Activities. Usa etiquetas, filtros y condicionales para personalizar dinámicamente el contenido de mensajes. Para aprender más sobre la sintaxis Liquid, consulta la documentación oficial de Liquid.

​
Campos soportados por tipo de mensaje

  • Email
  • Push
  • SMS
  • In-App Messages
  • Live Activities
  • Asunto, Responder a y Pre-encabezado
  • Cuerpo del mensaje
  • Sustitución de imagen en bloques HTML. Ejemplo: <img src="{{image_url}}"/>
  • Acciones de bloque de botón como URLs, Mail to y otros campos.

​
Sintaxis básica

Liquid usa dos estructuras de sintaxis principales:
  1. Etiquetas de salida: {{ ... }} - Muestra datos de una variable u objeto.
  2. Etiquetas de lógica: {% ... %} - Ejecuta declaraciones condicionales o bucles.

​
Fuentes de datos

FuenteEjemploDescripción
Tag{{ first_name }}SDK o API de OneSignal (tags)
Propiedad{{ subscription.email }}Gestionado por el sistema (email, external_id, language, etc.)
Nombre de Journey{{ journey.name }}Gestionado por el sistema
Datos personalizados{{ message.custom_data.key }}custom_data pasado en API Create Message
Data Feeds{{ data_feed.cart.size }}Data Feeds te permite obtener datos en tiempo real de tus APIs directamente en mensajes al momento del envío.
Eventos personalizados{{ journey.last_event.name }}Establecido a través de Journeys activados por eventos, nodos Wait Until

​
Condicionales

​
Operadores

  • ==, !=, >, <, >=, <=
  • and, or
  • contains (cadena o array)
Las operaciones se ejecutan de derecha a izquierda. Los paréntesis no son soportados.
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

Aplica filtros usando {{ variable | filter }} para ajustar cómo se muestran los datos.

​
default

Asigna un valor predeterminado si la propiedad está vacía o no existe.
liquid
Hello {{ first_name | default: "there" }}.

​
date

El filtro date convierte una marca de tiempo en otro formato de fecha. El formato para esta sintaxis es el mismo que strftime. La entrada usa el mismo formato que Time.parse de Ruby. Establece fechas como una marca de tiempo unix en segundos con tags. Esto permite el uso tanto de personalización con sintaxis liquid como de segmentación con Operadores de tiempo. Por ejemplo, un tag podría verse así: 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
El formato de fecha funciona en cadenas si contienen fechas bien formateadas.
liquid
{{ "March 14, 2016" | date: "%b %d, %y" }}
Result
Mar 14, 16
Para obtener la hora actual, pasa la palabra especial now (o today) junto con el 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.
La hora actual se renderizará en el mensaje según cuándo se envíe el mensaje al destinatario. Si estás probando el mensaje, verás la hora actual como cuando se envió el mensaje de prueba.

​
capitalize

Este filtro hace que el primer carácter de una cadena esté en mayúscula y convierte los caracteres restantes a minúsculas.
liquid
{{ "my GREAT title" | capitalize }}
Result
My great title

​
round

Este filtro redondea un número al entero más cercano, o, si se pasa un número como argumento, a ese número de decimales.
liquid
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
Result
1
3
183.36

​
pluralize

Este filtro devuelve la forma singular o plural de una cadena basándose en un número dado. El número debe ser un número entero y puede proporcionarse como cadena. Deben proporcionarse tanto la forma singular como la plural de una cadena.
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

​
Iteración

​
Bucles for

Ejecuta repetidamente un bloque de código. Para una lista completa de atributos disponibles dentro de un bucle for, consulta el objeto de bucle 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
Aunque poderosos y flexibles, el uso de bucles for en sintaxis liquid puede llevar a un rendimiento deficiente en la entrega de notificaciones en ciertos casos raros. Ten cuidado con tu uso de bucles for. También ten en cuenta que prevenimos el uso de bucles for en algunos campos de Canal Push: contents, headings, subtitle, apns_alert, y url

​
limit & offset

Limita el bucle al número especificado de iteraciones. Por ejemplo, si solo quieres mostrar 4 productos en un mensaje, podrías usar Límites y Desplazamientos para especificar el número de productos mostrados.
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
Result
1 2
Para comenzar el bucle en el índice especificado, agrega un valor de desplazamiento:
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

Crea un array que incluye solo los objetos con un valor de propiedad dado, o cualquier valor verdadero por defecto. En este ejemplo, supón que tienes una lista de productos y quieres mostrar tus productos de cocina por separado. Usando where, puedes crear un array que contenga solo los productos que tienen un 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

​
Manipulación de cadenas

Ocasionalmente puedes tener tags de datos que contienen cadenas en un formato que no es adecuado para mostrarse directamente a tus usuarios, y puede que necesites manipular la cadena para ajustar el formato. A continuación se muestra una tabla de comandos de sintaxis liquid que se pueden usar para ajustar cadenas. Puedes usar manipulación de cadenas tanto en Tags como directamente en cadenas escritas en el mensaje.
ComandoDescripciónEjemploSalida de ejemplo
replaceReemplaza una subcadena con otra cadena.{{ 'hello world' | replace: 'world', 'there' }}hello there
capitalizeCapitaliza la primera letra de una cadena.{{ 'hello' | capitalize }}Hello
upcaseConvierte una cadena a mayúsculas.{{ 'hello' | upcase }}HELLO
downcaseConvierte una cadena a minúsculas.{{ 'HELLO' | downcase }}hello
stripElimina espacios en blanco iniciales y finales de una cadena.{{ ' hello ' | strip }}hello
strip_htmlElimina todas las etiquetas HTML de una cadena.{{ '<p>hello</p>' | strip_html }}hello
truncateAcorta una cadena a una longitud especificada, agregando puntos suspensivos (…) si es necesario.{{ 'This is a long sentence' | truncate: 10 }}This is a…
truncatewordsTrunca una cadena después de un cierto número de palabras.{{ 'This is a long sentence' | truncatewords: 2 }}This is…
replace_firstReemplaza la primera ocurrencia de una subcadena.{{ 'hello world' | replace_first: 'world', 'there' }}hello there
prependAgrega una cadena al principio de otra cadena.{{ 'world' | prepend: 'hello ' }}hello world
appendAgrega una cadena al final de otra cadena.{{ 'hello' | append: ' world' }}hello world
lstripElimina espacios en blanco iniciales de una cadena.{{ ' hello' | lstrip }}hello
rstripElimina espacios en blanco finales de una cadena.{{ 'hello ' | rstrip }}hello

​
Preguntas frecuentes

​
¿Por qué no funciona la sustitución?

  • Los Mensajes In-App no soportan sustitución de propiedades.
  • La sustitución de tag no funciona cuando se usa “Send Test Message”.
  • Las claves de tag deben ser alfanuméricas, o usar _ y - (sin puntos ni espacios).
  • La sustitución no aparece en modo de vista previa — envía un mensaje real para probar.

​
¿Cómo controlar espacios en blanco y saltos de línea?

Usa guiones: {{- ... -}}, {%- ... -%} para recortar espacios en blanco circundantes. Ver Control de espacios en blanco para más detalles.

​
¿Cómo manejar contenido generado por usuarios?

Envuelve el texto generado por usuarios en {% raw %} y {% endraw %} para prevenir el análisis de Liquid. Ver sintaxis “raw”.
json
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}