Pular para o conteúdo principal
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.

​
Quando usar custom_data

Use custom_data quando você precisa:
  • Dados que mudam por mensagem (totais de pedidos, itens do carrinho, saldos)
  • Você precisa de arrays (listas de produtos, itens de linha, recomendações)
  • Dados que não devem persistir (códigos únicos, URLs temporárias)
  • Você envia mensagens disparadas pelo backend
  • Você quer personalização em massa em uma única requisição de API

​
Como funciona a personalização com custom_data

Adicionar custom_data às mensagens requer alguns passos:
1

Crie um template

Crie um template de Push, Email ou SMS em Templates no painel ou via Create Template API.
2

Adicione placeholders Liquid

Insira referências usando o prefixo obrigatório:
Liquid
Hi {{ message.custom_data.first_name }},
Order {{ message.custom_data.order_id }} is confirmed.
3

Envie custom_data na sua requisição de API

Chame a Create Message API com:
  • template_id - O ID do template
  • custom_data - O objeto de dados
  • 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.

​
Padrões de dados

Exemplos comuns de padrões de dados que você pode usar com custom_data.

​
Exemplo de JSON plano

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.
Requisição de API:
JSON
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "invoice_id": "463246732",
    "product_name": "Widget"
  }
}
O que o cliente vê:
Text
Invoice 463246732 for Widget is ready.

​
Exemplo de dados com array

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 %}
Requisição de API: 
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["user@example.com"],
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://.../sweater.png"
      },
      {
        "item_name": "socks",
        "img_url": "https://.../socks.png"
      }
    ]
  }
}
O que o cliente vê:
Text
Your sweater is waiting for you!
Image: https://.../sweater.png

- sweater — https://.../sweater.png
- socks — https://.../socks.png
Propriedades úteis de arrays:
  • {{message.custom_data.cart_items.size}} — Número de itens no array (retorna 2 neste exemplo)
  • {{message.custom_data.cart_items.first.item_name}} — Nome do primeiro item (equivalente a [0])
  • {{message.custom_data.cart_items.last.item_name}} — Nome do último item

​
Exemplo de personalização em massa

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:
  1. Estruture custom_data como um objeto onde as chaves são external_ids e os valores são dados específicos do usuário
  2. No template, use subscription.external_id para buscar os dados do destinatário atual
  3. 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
Requisição de API: 
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user123", "user456"]
  },
  "custom_data": {
    "users": {
      "user123": { "first_name": "John", "points": "150", "level": "Gold" },
      "user456": { "first_name": "Sarah", "points": "200", "level": "Platinum" }
    }
  }
}
O que cada usuário vê:
  • John (user123): “Hi John, you have 150 points. Your level is Gold.”
  • Sarah (user456): “Hi Sarah, you have 200 points. Your level is Platinum.”
Requisitos para personalização em massa:
  • Todos os destinatários devem ter um external_id definido no OneSignal
  • Cada external_id em include_aliases deve ter uma chave correspondente em custom_data.users
  • Se o external_id de um destinatário estiver ausente em custom_data, a mensagem dele terá campos vazios

​
Exemplo: Carrinho abandonado com custom_data

Como criar mensagens de carrinho abandonado para email e push usando custom_data. Quando usar esta abordagem:
  • Seu servidor detecta o abandono de carrinho (ex.: 1 hora após a última atividade)
  • Os dados do carrinho em tempo real estão no seu banco de dados
  • Você quer exibir múltiplos produtos com imagens, nomes e preços
  • Cada usuário pode ter itens e quantidades diferentes
  • Você quer orquestrar a mensagem a partir do seu backend

​
Exemplo de payload custom_data

Esta é a requisição da Create Message API para este exemplo.
JSON
{
  "custom_data": {
    "cart_url": "https://yourdomain.com/cart",
    "cart": [
      {
        "product_name": "24 Pack of Acorns",
        "product_image": "https://i.imgur.com/ssPCfbC.png",
        "product_price": "$12.99",
        "product_quantity": "1"
      },
      {
        "product_name": "Fancy Sweater",
        "product_image": "https://i.imgur.com/8QWTfV4.png",
        "product_price": "$9.99",
        "product_quantity": "1"
      }
    ]
  },
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["YOUR_EXTERNAL_ID"]
  }
}
Explicação dos campos:
CampoTipoFinalidade
cart_urlstringLink único do carrinho do cliente (para botões/URLs de abertura)
cartarrayLista de produtos — suporta contagem, loops e exibição de detalhes
product_imagestringImagem do produto (por item no array)
product_namestringNome do produto (por item)
product_quantitystringQuantidade (por item)
product_pricestringPreç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.

​
Template de email

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
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
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):
HTML
<img src="{{product.product_image}}" alt="Product image" style="max-width:100%;" />
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}}
8

Teste o template

  • Configure sua requisição de API usando o Exemplo de payload custom_data
  • Envie o email para você mesmo.
  • Verifique se os dados são exibidos corretamente.
Sucesso! Agora você pode aplicar seu próprio estilo ao template. Consulte Design de emails com drag-and-drop.

​
Template de push

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:
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 %}
Consulte Usando sintaxe Liquid para mais informações.
Campo de imagem:
Liquid
{{message.custom_data.cart.first.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
Consulte Imagens de notificação e rich media para mais informações.
Campo de URL de abertura:
Liquid
{{cart_url | default: "https://yourdomain.com/cart"}}
Sucesso! Salve o template e use seu template_id na requisição de API Create message com a propriedade custom_data para testar.

​
Solução de problemas e boas práticas

  • Mantenha simples: Inclua apenas dados que você realmente usará no template
  • Mantenha abaixo de 2KB: Monitore o tamanho do seu payload, especialmente com arrays
  • Use nomenclatura consistente: Mantenha snake_case ou camelCase em todo o código
  • Valide antes de enviar: Verifique valores nulos, arrays vazios e campos obrigatórios
Design de template:
  • Sempre use filtros default para campos opcionais:
    Liquid
    {{message.custom_data.user_name | default: "there"}}
  • Verifique o tamanho do array antes de iterar:
    Liquid
    {% if message.custom_data.items.size > 0 %}
  {% for item in message.custom_data.items %}
    {{item.name}}
  {% endfor %}
{% endif %}
  • Teste com casos extremos: arrays vazios, campos ausentes, contagens máximas de itens
Tratamento de erros:
  • Registre as respostas da API no lado do servidor para capturar erros de validação
  • Monitore as taxas de entrega de mensagens — quedas repentinas podem indicar erros de Liquid
  • Mantenha templates de fallback prontos para mensagens transacionais críticas
Performance:
  • Pré-formate dados complexos no seu backend em vez de usar lógica Liquid complexa
  • Faça cache de templates e reutilize-os em muitas chamadas de API
  • Considere separar mensagens transacionais de alto volume de campanhas de marketing
Causa: Erros de sintaxe Liquid ou nomes de campos incompatíveisSoluções:
  • Verifique se os nomes dos campos correspondem exatamente entre custom_data e o template (diferencia maiúsculas e minúsculas)
  • Verifique erros de digitação: {{message.custom_data.name}} e não {{message.custm_data.name}}
  • Use filtros default para capturar campos ausentes
  • Teste templates com a estrutura real de custom_data antes de colocar em produção
Causa: custom_data excede o limite de 2KBSoluções:
  • Remova campos desnecessários do seu payload
  • Encurte nomes de campos e valores quando possível
  • Limite arrays aos primeiros 3-5 itens
  • Mova conteúdo estático grande (como HTML completo) para o seu template

​
Páginas relacionadas

Personalização de mensagens

Visão geral de todas as opções de personalização no OneSignal, incluindo Data Tags, atributos de usuário e segmentação.

Create Message API

Referência completa da API para envio de mensagens com custom_data, opções de segmentação e todos os campos disponíveis.

Usando sintaxe Liquid

Referência completa de sintaxe Liquid incluindo filtros, condicionais, loops e manipulação de strings.

Templates

Crie e gerencie templates de mensagens reutilizáveis para canais de Push, Email, SMS e In-App.
Precisa de ajuda?Converse com nossa equipe de Suporte ou envie email para support@onesignal.comPor favor inclua:
  • Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  • Seu OneSignal App ID
  • O External ID ou Subscription ID se aplicável
  • A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  • Quaisquer logs ou mensagens de erro relevantes
Estamos felizes em ajudar!