Data feeds - OneSignal

Data Feeds permitem que você busque dados em tempo real de suas APIs diretamente em mensagens no momento do envio. Isso permite entregar conteúdo altamente personalizado sem pré-carregar dados no OneSignal. Use Data Feeds quando seus dados mudam frequentemente, como:

Saldo de recompensas atual de um usuário
Status de pedido mais recente
Recomendações personalizadas de produtos

Outros métodos de personalização (como Tags ou Conteúdo Dinâmico) funcionam bem para dados estáticos. Data Feeds são melhores para valores ao vivo e que mudam rapidamente.

Data Feeds estão atualmente disponíveis apenas para mensagens de email enviadas através de Journeys. Precisa de outro canal? Preencha esta breve pesquisa.

Como funcionam os Data Feeds

Criar um Data Feed – Configure como o OneSignal se conecta à sua API.
Anexar o Data Feed a um template de mensagem.
Inserir campos de resposta na sua mensagem usando sintaxe Liquid.
No momento do envio, o OneSignal faz uma chamada de API para cada destinatário, analisa a resposta e injeta os dados na sua mensagem.

Exemplo: Exibir pontos de recompensa

Suponha que você queira mostrar a cada cliente seu saldo de recompensas:

Olá {{ first_name }},

Você tem {{ data_feed.rewards.points }} pontos!
Seu status de membro é {{ data_feed.rewards.status_level }}.

Continue comprando para ganhar mais pontos!

Quando Sarah receber este email, as variáveis Liquid são substituídas pelo seu saldo real de pontos e status de membro. As seções a seguir mostram como configurar este exemplo passo a passo.

Criando e usando um Data Feed

1. Configurar seu Data Feed

Navegue até Data > Data Feeds na barra lateral para ver a lista de Data Feeds existentes e criar um novo. Cada Data Feed deve ter:

Name: Um nome descritivo como “Customer Rewards API” para ajudá-lo a distinguir feeds. Nomes únicos são recomendados, mas não obrigatórios.
Alias: Um identificador curto como rewards usado na sintaxe Liquid (ex.: {{ data_feed.rewards.points }}). Deve ser único, em minúsculas, alfanumérico, sem espaços ou caracteres especiais.
Method: O método HTTP que o OneSignal usa para contatar sua API. Geralmente GET, mas POST também é suportado.
URL: Seu endpoint de API. Suporta sintaxe Liquid para que o OneSignal possa buscar dados específicos do usuário.

Por exemplo, seu endpoint de recompensas pode aceitar o external_id do usuário (armazenado no OneSignal) como parâmetro de URL:

https://acme.com/customers/user_id={{ external_id }}/rewards

Headers: Pares chave-valor exigidos pela sua API (ex.: tokens de autenticação). Suporta sintaxe Liquid.
Body: Body de solicitação JSON opcional. Suporta sintaxe Liquid, da mesma forma que webhooks de Journey.

Por exemplo, sua API pode exigir o ID do usuário no body da solicitação em vez da URL:

{
	"customer_id": "{{ subscription.external_id }}"
}

Uma configuração completa de Data Feed tem esta aparência:

Data Feed configuration showing name, alias, method, URL, and headers

Teste seu feed antes de usá-lo em produção. Os testes de Data Feed são executados em suas assinaturas de teste, portanto verifique se essas assinaturas possuem atributos que retornam um resultado real da sua API.

Por fim, Ative seu novo Data Feed para que fique pronto para uso.

2. Anexar o Data Feed ao seu template de mensagem

Anexe seu Data Feed ao seu template de mensagem para que o OneSignal saiba usá-lo.

Navegue até Messages > Templates
Na seção Message, selecione o botão Personalization

Personalization button in the message template editor

Ative Data Feeds e selecione seu feed

Data Feeds toggle and feed selector in the message composer

Salve seu template

3. Usar os dados na sua mensagem

Use sintaxe Liquid para inserir dados de resposta em qualquer lugar da sua mensagem. Continuando o exemplo de recompensas, a resposta da API para Sarah (cujo external_id é a1-b2c3) pode ser assim:

{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}

Para inserir o número de pontos e o nível de status, use notação de ponto para referenciar o alias do Data Feed e os campos de resposta:

Você tem {{ data_feed.rewards.points }} pontos!
Seu status de membro é {{ data_feed.rewards.status_level }}.

Isso diz ao OneSignal:

Use um Data Feed
Use o Data Feed rewards
- Lembre-se: o feed rewards sabe chamar a API com o external_id do destinatário
Da resposta, insira o valor do item points (193) e do item status_level (Gold)

Requisitos e limites

Sua API precisa:

Aceitar autenticação de etapa única com tokens de autenticação em cabeçalhos
Responder rapidamente. Menos de 250ms recomendado (isso afeta diretamente a velocidade de envio)
Retornar JSON. Outros formatos não são suportados no momento.
- Se você precisa de um formato diferente, compartilhe seu caso de uso.
Lidar com seu volume de envio. Um limite de taxa baixo na sua API reduz a velocidade de entrega das mensagens.
Retornar payloads de tamanho razoável. Mantenha as respostas abaixo de 50 KB para melhor desempenho.

Limites atuais:

Um Data Feed por template. Busque tudo o que você precisa em uma única resposta de API.
Uma chamada de API por Data Feed por mensagem.
Apenas Journeys. Ainda não disponível para outros métodos de envio.
Sem encadeamento de chamadas. O payload de um Data Feed não pode ser usado para chamar outro.

Precisa de múltiplos Data Feeds por template ou suporte para outros canais? Compartilhe seu caso de uso para ajudar a priorizar esses recursos.

Configurando sua API

Antes de criar um Data Feed, certifique-se de que sua API pode atender a esses requisitos:

Autenticação

Sua API deve aceitar autenticação via cabeçalhos:

Authorization: Bearer YOUR_TOKEN

X-API-Key: YOUR_KEY

Body de solicitação JSON

Se você precisa incluir um body na solicitação, sua API deve aceitar JSON. Isso pode significar que seus cabeçalhos precisam incluir Content-Type: application/json.

Resposta JSON

Sua API deve retornar um objeto JSON. Tipicamente isso significa que seus cabeçalhos incluirão Accept: application/json.

Parâmetros de personalização

Você normalmente passará identificadores de usuário na URL assim:

https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}

E/ou no body:

{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}

Certifique-se de que esses dados existirão no OneSignal (geralmente como Tags, mas outras opções estão disponíveis, como propriedades de eventos personalizados).

Limites de taxa

Considere os limites de taxa da sua API. Enviar para 10.000 usuários significa 10.000 chamadas de API em rápida sucessão. Certifique-se de que sua API pode lidar com esse volume.

Tratamento de erros

Se sua API retornar um erro ou não tiver dados para um usuário, a mensagem não será enviada para aquele destinatário. Certifique-se de que sua API retorna dados para todos os usuários esperados.

Checklist de primeiros passos

Antes de implementar Data Feeds, responda estas perguntas:

Quais dados eu quero mostrar na minha mensagem? Trabalhar de trás para frente a partir de um esboço simples com os itens a serem preenchidos pela sua API identificados ajudará você a organizar seu pensamento.
Esses dados estão disponíveis através de um único endpoint de API?
Como vou autenticar solicitações de API?
Qual identificador ou outro item de dados vou usar para buscar dados personalizados?
Esse identificador já está armazenado no OneSignal? Se não, como será preenchido?
Minha API pode lidar com o volume de solicitações que vou gerar?
O que acontece se minha API não tiver dados para um usuário?

Exemplos e casos de uso avançados

Data Feeds podem ser usados com sintaxe Liquid ou em combinação com outros recursos de formas criativas para produzir personalização mais complexa.

Iterando com loops: carrinho abandonado
Propriedades de eventos personalizados
Exibição condicional: status do pedido
Automação sem personalização
Códigos de cupom personalizados

Digamos que você tem um Data Feed cart que retorna um array de itens no carrinho do usuário, mais o valor total em dólares do carrinho:

{
  "items": [
    {
      "name": "Blue Running Shoes",
      "price": 84.00,
      "image_url": "https://acme.com/blue-running-shoes.png"
    },
    {
      "name": "Protein Bar",
      "price": 5.99,
      "image_url": "https://acme.com/protein-bar.png"
    }
  ],
  "total": 89.99
}

Se você quiser mostrar cada item no carrinho, mais o total do carrinho, você pode usar um loop for em Liquid:

<ul>
  {% for item in data_feed.cart.items %}
    <li>
      <strong>{{ item.name }}</strong><br>
      ${{ item.price }}<br>
      <img src="{{ item.image_url }}" alt="{{ item.name }}">
    </li>
  {% endfor %}
</ul>

<p>Cart total: ${{ data_feed.cart.total }}</p>

Isso resultará em:

- Blue Running Shoes
- $84.00
- <imagem de tênis de corrida>
- Protein Bar
- $5.99
- <imagem de barra de proteína>
Cart total: $89.99

Se você está usando o editor de blocos de email, ao inserir este tipo de sintaxe Liquid complexa, particularmente se você precisar incluir imagens ou links, para melhores resultados use o elemento de bloco HTML personalizado.

Quer ver como acionar este email de carrinho abandonado usando eventos personalizados? Confira a aba Propriedades de eventos personalizados para o fluxo de trabalho completo.

Continuando o exemplo anterior de carrinho abandonado, como poderíamos saber como buscar aquele carrinho específico em primeiro lugar?Um método poderia ser criar uma Journey acionada por um evento personalizado cart_abandoned, onde as propriedades incluem um cart_id. Neste exemplo, esse evento está sendo enviado ao OneSignal via API:

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "properties": {
        "cart_id": 98765
      }
    }
  ]
}'

Journey entry node triggered by a custom event

O usuário user_12345 entra na jornada quando este evento é disparado, depois alcança um nó enviando um email. Esse template de email está configurado com o Data Feed cart, onde a URL está definida para recuperar o conteúdo de um carrinho específico assim:

https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}

Assim, quando este evento específico é ingerido e aciona a Journey:

O valor cart_id de 98765 será armazenado na Journey
Quando a etapa de email for alcançada, o Data Feed cart referenciará aquele valor cart_id e o usará para chamar a API do carrinho
As propriedades JSON retornadas serão analisadas e inseridas no email como no exemplo anterior acima

Quer ver como exibir condicionalmente conteúdo de Data Feed com base no status do pedido? Confira a aba Exibição condicional: status do pedido para saber mais.

Digamos que você queira incluir o status do pedido de um cliente, mas só incluir um link de número de rastreamento se o pedido foi enviado. Você pode usar uma instrução if para fazer isso:

Seu pedido está {{data_feed.order.status}}!

{% if data_feed.order.tracking_number != empty %}
Rastreie aqui: {{data_feed.order.tracking_url}}
{% endif %}

Aqui, o link de rastreamento só será exibido se o tracking_number existir.

Data Feeds podem ser usados para inserir automaticamente informações atualizadas em suas mensagens sem necessariamente precisar ser personalizado por destinatário.Por exemplo, talvez você insira uma imagem de banner no topo dos seus emails e a altere mensalmente para acompanhar feriados e outros eventos mensais. Em vez de lembrar de fazer upload de uma nova imagem para o OneSignal e alterar todos os seus templates a cada mês, você pode configurar um Data Feed que busque a URL da imagem do banner atual do seu CMS ou outro local de gerenciamento de ativos.Você configuraria um Data Feed banner que aponta para um endpoint sem quaisquer variáveis na URL assim:

https://acme.com/assets/email-banner

Que retorna uma resposta com a URL do banner atual:

{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}

Você definiria seu template de email para usar {{ data_feed.banner.banner_url }} como a URL de origem da imagem, automatizando este processo daqui em diante.

Este exemplo mostra como enviar códigos de cupom personalizados e de uso único em emails usando um Data Feed que busca um valor único da sua API para cada destinatário.

Objetivo

Enviar um email como:

Olá George, Conclua sua reserva nas próximas 2 horas e economize 10% com seu código pessoal: XYZ123ABC

Cada usuário recebe um código de cupom único, gerado ao vivo via uma chamada de API externa quando o email é enviado, válido para a janela de tempo determinada e vinculado a aquele usuário.

Pré-requisitos

Canal de email configurado no OneSignal (seu app tem a capacidade de email habilitada)
Uma API externa que aceita um identificador de usuário (por exemplo, external_id) e um identificador de campanha, e retorna JSON com o código de cupom, desconto e expiração
Um identificador único (como external_id) para cada usuário que sua API pode usar para gerar cupons
Um segmento ou gatilho (por exemplo, “busca abandonada nas últimas 24h”) usado para enviar o email através de uma Journey do OneSignal

Passo 1: Criar o Data Feed

Navegar para Data Feeds

No seu app do OneSignal, selecione Data feeds na barra de navegação, depois clique em New data feed.

Configurar o Data Feed

Configure os seguintes campos:

Data Feed Name: coupon_code_generator
Alias: coupon
Method: GET
URL: https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10

Headers:

{
  "Authorization": "Bearer YOUR_API_TOKEN"
}

Referenciar a resposta da API

Quando a API retornar JSON como este:

{
  "code": "AB10-5F3K-HT9L",
  "discount_percent": "10%",
  "expires_in_hours": 2
}

Você pode referenciar seus valores no seu template de email como:

{{ data_feed.coupon.code }}
{{ data_feed.coupon.discount_percent }}
{{ data_feed.coupon.expires_in_hours }}

Testar e ativar o Data Feed

Clique em Send Test para verificar sua configuração, depois clique em Activate para tornar o Data Feed disponível para uso em templates.

Passo 2: Criar o template de email

No OneSignal, vá para Messages → Email → New Template
Use o alias e os campos do Data Feed no corpo da sua mensagem. Por exemplo:

<h2>Olá {{ first_name }},</h2>
<p>
Conclua sua reserva nas próximas {{ data_feed.coupon.expires_in_hours }} horas e economize
{{ data_feed.coupon.discount_percent }} com seu código pessoal:
<strong>{{ data_feed.coupon.code }}</strong>
</p>

<p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Usar Código Agora →</a></p>

Use sintaxe Liquid no formato {{ data_feed.<alias>.<field> }}
Certifique-se de que o Data Feed está anexado ao template
Se estiver usando o editor de arrastar e soltar com lógica Liquid personalizada, use um bloco HTML

Passo 3: Anexar o Data Feed e acionar o email

No compositor de template, em Personalization, ative Data Feeds e selecione seu feed (coupon_code_generator)
Isso garante que o OneSignal faça a chamada de API no momento do envio para cada destinatário, preencha os dados e os injete no email
Configure uma Journey para automatizar a mensagem:
- Condição de entrada: Segmento como “busca abandonada nas últimas 24 horas”
- Wait until: Crie um evento personalizado booking_completed. Configure a espera para sair da Journey se este evento for disparado, ou continuar após 1 hora. Se concluírem uma reserva, saem sem receber o email; caso contrário, continuam para receber o cupom.
- Send email: Use o template de email com cupom personalizado
- Certifique-se de que a Journey usa o canal de email e que os destinatários estão inscritos no email

Passo 4: Gerenciar o resgate e rastreamento de cupons

Seu backend deve:

Registrar cada código gerado juntamente com userId, code, campaign, expiration_time e um indicador redeemed
Validar e marcar códigos como resgatados no checkout
Registrar os dados de resgate (usuário, campanha e horário) para análise de ROI

Exemplo de fluxo de trabalho completo

Passo	Evento	Ação
1	Usuário aciona segmento “busca abandonada”	Usuário entra na Journey via segmento
2	Journey aciona envio de email	OneSignal anexa o Data Feed, chama sua API com o `external_id` e nome da campanha do usuário
3	API retorna JSON	OneSignal preenche os campos do cupom do data feed e envia o email
4	Usuário recebe o email	Exemplo: “Olá George! Economize 10% com seu código pessoal: AB10-5F3K-HT9L”
5	Usuário resgata o código	Backend valida e registra o resgate

Testes

Teste com um usuário que tem um external_id conhecido
Chame sua API manualmente para confirmar respostas JSON corretas
Use Preview no editor de templates do OneSignal para verificar se os campos do cupom do data feed são preenchidos
Verifique os logs da API para latência e erros
Se uma chamada de Data Feed falhar, o OneSignal ignorará o envio da mensagem para aquele destinatário

Perguntas frequentes

Os valores do meu Data Feed não estão aparecendo na mensagem. O que devo verificar?

Verifique nesta ordem:

O Data Feed está anexado ao template (em Personalization > Data Feeds).
Sua sintaxe Liquid corresponde à estrutura de resposta JSON exatamente — {{ data_feed.<alias>.<field> }}.
O endpoint da API retorna JSON válido quando chamado manualmente com os mesmos identificadores.
O destinatário tem o identificador necessário (ex.: external_id) armazenado no OneSignal.

Por que as mensagens estão sendo enviadas lentamente?

As chamadas de API do Data Feed são executadas no momento do envio para cada destinatário. Se sua API responde lentamente ou não consegue lidar com solicitações simultâneas, a entrega de mensagens reduz proporcionalmente. Procure tempo de resposta abaixo de 250 ms e certifique-se de que sua infraestrutura pode lidar com seu volume de envio.

Por que alguns destinatários não estão recebendo mensagens?

Se a chamada de API do Data Feed falhar para um destinatário — devido a um 404, timeout ou dados ausentes — o OneSignal ignora aquele destinatário completamente. Verifique o log de erros na configuração do seu Data Feed e os logs da sua própria API para falhas. Verifique se esses usuários têm os identificadores necessários no OneSignal.

Posso usar mais de um Data Feed em um template?

Não no momento. Cada template suporta um Data Feed. Busque todos os dados necessários em uma única resposta de API. Se você precisar de múltiplos feeds, compartilhe seu caso de uso.

Data Feeds estão disponíveis para notificações push ou SMS?

Não. Data Feeds estão atualmente disponíveis apenas para mensagens de email enviadas através de Journeys. O suporte para canais adicionais está planejado — compartilhe seu caso de uso para ajudar a priorizar.

O que acontece se minha API estiver fora do ar quando a mensagem for enviada?

O OneSignal ignora qualquer destinatário cuja chamada de Data Feed falhar. A mensagem não é enviada para aquele destinatário e nenhum valor de fallback é inserido. Monitore o uptime e as taxas de erro da sua API durante envios programados.

Páginas relacionadas

Sintaxe Liquid

Referência completa para templates Liquid em mensagens do OneSignal.

Journeys

Crie fluxos de trabalho de mensagens automatizadas que acionam emails com Data Feed.

Eventos personalizados

Acione Journeys e passe propriedades de eventos para URLs de Data Feed.

Personalização de mensagens

Visão geral de todos os métodos de personalização — tags, Liquid, conteúdo dinâmico e Data Feeds.

Primeiros passos & configurações

Canais de mensagem

Jornadas

Público & eventos personalizados

Análises & Integrações

Privacidade & Segurança

​Como funcionam os Data Feeds

​Exemplo: Exibir pontos de recompensa

​Criando e usando um Data Feed

​1. Configurar seu Data Feed

​2. Anexar o Data Feed ao seu template de mensagem

​3. Usar os dados na sua mensagem

​Requisitos e limites

​Configurando sua API

​Autenticação

​Body de solicitação JSON

​Resposta JSON

​Parâmetros de personalização

​Limites de taxa

​Tratamento de erros

​Checklist de primeiros passos

​Exemplos e casos de uso avançados

​Objetivo

​Pré-requisitos

​Passo 1: Criar o Data Feed

​Passo 2: Criar o template de email

​Passo 3: Anexar o Data Feed e acionar o email

​Passo 4: Gerenciar o resgate e rastreamento de cupons

​Exemplo de fluxo de trabalho completo

​Testes

​Perguntas frequentes

​Os valores do meu Data Feed não estão aparecendo na mensagem. O que devo verificar?

​Por que as mensagens estão sendo enviadas lentamente?

​Por que alguns destinatários não estão recebendo mensagens?

​Posso usar mais de um Data Feed em um template?

​Data Feeds estão disponíveis para notificações push ou SMS?

​O que acontece se minha API estiver fora do ar quando a mensagem for enviada?

​Páginas relacionadas

Sintaxe Liquid

Journeys

Eventos personalizados

Personalização de mensagens

Como funcionam os Data Feeds

Exemplo: Exibir pontos de recompensa

Criando e usando um Data Feed

1. Configurar seu Data Feed

2. Anexar o Data Feed ao seu template de mensagem

3. Usar os dados na sua mensagem

Requisitos e limites

Configurando sua API

Autenticação

Body de solicitação JSON

Resposta JSON

Parâmetros de personalização

Limites de taxa

Tratamento de erros

Checklist de primeiros passos

Exemplos e casos de uso avançados

Objetivo

Pré-requisitos

Passo 1: Criar o Data Feed

Passo 2: Criar o template de email

Passo 3: Anexar o Data Feed e acionar o email

Passo 4: Gerenciar o resgate e rastreamento de cupons

Exemplo de fluxo de trabalho completo

Testes

Perguntas frequentes

Os valores do meu Data Feed não estão aparecendo na mensagem. O que devo verificar?

Por que as mensagens estão sendo enviadas lentamente?

Por que alguns destinatários não estão recebendo mensagens?

Posso usar mais de um Data Feed em um template?

Data Feeds estão disponíveis para notificações push ou SMS?

O que acontece se minha API estiver fora do ar quando a mensagem for enviada?

Páginas relacionadas