Envie dados dinâmicos e específicos por mensagem através da Create Message API usando custom_data. Referencie valores em templates com sintaxe Liquid para personalização em tempo real.
Use o campo custom_data na Create Message API para enviar dados dinâmicos do seu backend e renderizá-los dentro de templates usando sintaxe Liquid.custom_data:
É específico da mensagem
Não é armazenado
Existe apenas durante a requisição da API
Deve ser usado com um template_id
Referencie valores nos templates com:
Liquid
{{ message.custom_data.key_name }}
custom_data é efêmero. Os dados não são salvos nos perfis de usuário e não podem ser reutilizados em mensagens futuras. Se você precisa de dados persistentes, consulte Personalização de mensagens.
Segmentação de audiência (include_player_ids, include_aliases ou segments)
O OneSignal renderiza o template no momento do envio usando seus dados.Se a sintaxe Liquid for inválida ou as chaves não existirem, esses campos são renderizados como strings vazias, mas a mensagem ainda é enviada.
Use pares chave-valor simples para personalização básica como nomes, IDs, URLs ou qualquer dado de valor único.Caso de uso: Mensagens transacionais (faturas, recibos, confirmações) onde cada campo contém um único valor.Template:
Liquid
Invoice {{ message.custom_data.invoice_id }} for {{ message.custom_data.product_name }} is ready.
Passe arrays de objetos para trabalhar com múltiplos itens como produtos do carrinho, itens de linha de pedidos ou recomendações. Arrays permitem tanto acesso direto (indexação) quanto iteração (loops).Caso de uso: Exibição de listas de produtos, rankings, resumos de pedidos ou qualquer dado com múltiplos itens.Template de indexação (acessando o primeiro item):
Liquid
Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!Image: {{message.custom_data.cart_items[0].img_url}}
A indexação de arrays começa em 0, não em 1. O primeiro item é [0], o segundo é [1], etc. Acessar um índice que não existe retorna vazio (nenhum erro é lançado).
Template com loop (acessando todos os itens):
Liquid
{% for item in message.custom_data.cart_items %}- {{ item.item_name }} — {{ item.img_url }}{% endfor %}
Envie uma única requisição de API para múltiplos usuários onde cada destinatário vê conteúdo personalizado com base no seu external_id.Como funciona:
Estruture custom_data como um objeto onde as chaves são external_ids e os valores são dados específicos do usuário
No template, use subscription.external_id para buscar os dados do destinatário atual
O OneSignal renderiza o template uma vez por destinatário com seus dados específicos
Template:
{% assign user = message.custom_data.users[subscription.external_id] %}Hi {{ user.first_name }}, you have {{ user.points }} points. Your level is {{ user.level }}.
O que está acontecendo:
subscription.external_id contém o external_id do destinatário atual (ex.: “user123”)
message.custom_data.users[subscription.external_id] busca os dados desse usuário no objeto custom_data
user se torna uma variável de atalho para os dados desse usuário
Cada destinatário vê apenas seu próprio conteúdo personalizado
Link único do carrinho do cliente (para botões/URLs de abertura)
cart
array
Lista de produtos — suporta contagem, loops e exibição de detalhes
product_image
string
Imagem do produto (por item no array)
product_name
string
Nome do produto (por item)
product_quantity
string
Quantidade (por item)
product_price
string
Preço com formatação (por item)
Você pode nomear os campos como quiser — apenas certifique-se de que a sintaxe Liquid do seu template corresponda.
Mantenha abaixo de 2KB: Se você tem carrinhos grandes, considere limitar aos primeiros 3-5 itens ou enviar apenas campos essenciais para evitar exceder o limite de tamanho.
Este exemplo mostra como criar um template de email que exibe:
A contagem de itens do carrinho
Cada produto com imagem, nome, quantidade e preço usando um for-loop
Um botão que linka para a URL única do carrinho do cliente
Exemplo de template de email de carrinho abandonado
1
Crie o template de email
Navegue até Messages > Templates > New Email Template e abra o Editor Drag & Drop.
2
Adicione a estrutura de layout
Crie cinco linhas:
Linhas 1, 2 e 4: uma coluna com um bloco Paragraph
Linha 3: quatro colunas com HTML | Paragraph | Paragraph | Paragraph
Linha 5: uma coluna com um bloco Button
Template de email inicial para carrinho abandonado
3
Exiba a contagem de itens
Na linha 1, adicione:
Liquid
We're holding onto {{message.custom_data.cart.size}} items in your cart, but don't wait too long, other squirrels are getting ahead!
Para uma gramática melhor, você pode usar uma condicional para dizer “1 item” vs “2 items”, mas para emails de carrinho abandonado, o plural geralmente é aceitável.
Liquid
{% assign cart = message.custom_data.cart %}{% assign item_count = cart.size | plus: 0 %}{% if item_count == 1 %}We're holding onto {{item_count}} item in your cart, but don't wait too long, other squirrels are getting ahead!{% endif %}{% if item_count > 1 %}We're holding onto {{item_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!{% endif %}
4
Inicie o loop
Use um for-loop para repetir a linha de exibição do produto para cada item no carrinho.Na linha 2 (início do loop), adicione isto ao bloco de texto:
Text
{% for product in message.custom_data.cart %}
O que isto faz:
Inicia um loop que itera sobre cada objeto no array cart
Cria uma variável temporária chamada product que representa o item atual
Tudo entre {% for %} e {% endfor %} se repete uma vez por item do carrinho
Você pode nomear product como quiser (ex.: item, cartItem) — apenas mantenha a consistência
Posicionamento do for-loop: Certifique-se de que a sintaxe {% for %} esteja em sua própria linha de bloco de texto. Não coloque dentro de uma linha de múltiplas colunas com outro conteúdo, pois isso pode quebrar a renderização do email em alguns clientes.
5
Exiba os detalhes do produto
Esta linha de 4 colunas mostra imagem, nome, quantidade e preço. Como está dentro do loop, ela se repete para cada item do carrinho.Na linha 3 (detalhes do produto), configure:Coluna 1 - Bloco HTML (imagem do produto):
Colunas 2–4 - Blocos de texto (nome do produto, quantidade, preço):
Coluna 2: {{product.product_name}}
Coluna 3: {{product.product_quantity}}
Coluna 4: {{product.product_price}}
Como o loop funciona:
Na primeira iteração, product = primeiro objeto no array cart
{{product.product_image}} obtém a URL da imagem do primeiro item
Na segunda iteração, product = segundo objeto
A linha se repete automaticamente para todos os itens do carrinho
Correspondência de nomes de campos: Chaves como product_image devem corresponder exatamente ao seu payload de evento (diferencia maiúsculas e minúsculas). Nomes incompatíveis são renderizados como strings vazias.
6
Encerre o loop
Feche o loop para marcar onde a repetição termina.Na linha 4 (fim do loop), adicione:
Liquid
{% endfor %}
Todo {% for %} deve ter um {% endfor %} correspondente. Se estiver faltando, a renderização do email será quebrada.
7
Adicione um botão de link do carrinho
No bloco Button da linha 5, defina a URL de Ação para:
Text
{{message.custom_data.cart_url}}
Template base finalizado de email de carrinho abandonado sem estilização
Notificações push têm limites de caracteres e restrições do sistema operacional, então em vez de mostrar todos os itens, exiba o primeiro produto e indique a contagem total com gramática adequada.Aqui está um exemplo de notificação push que vamos construir:
Exemplo de template de push de carrinho abandonado
Campo de mensagem:
Liquid
{% assign cart = message.custom_data.cart %}{% assign item_count = cart.size | plus: 0 %}{% if item_count == 1 %}You left {{cart.first.product_name}} in your cart.{% endif %}{% if item_count == 2 %}You left {{cart.first.product_name}} and {{item_count | minus: 1}} more item in your cart.{% endif %}{% if item_count > 2 %}You left {{cart.first.product_name}} and {{item_count | minus: 1}} more items in your cart.{% endif %}
