Atividade social

Notifique usuários quando algo que os envolve acontecer: uma curtida, uma resposta, uma seguida, uma mensagem recebida ou um evento competitivo em um jogo. Essas notificações impulsionam o reengajamento mesmo quando os usuários não estão ativos no seu app no momento.

O OneSignal não foi projetado para comunicação em tempo real. As notificações push são melhor usadas como fallback quando os usuários não estão ativamente no app. Para mensagens em tempo real dentro do app, use a camada de mensagens existente do seu app e acione notificações do OneSignal apenas quando o destinatário estiver offline ou inativo.

Notifique usuários quando alguém curtir, comentar, mencionar, marcar ou segui-los.

Mensagens diretas

Alerte usuários sobre novas mensagens recebidas com debounce e deep links para a conversa.

Alertas de jogos

Envie eventos competitivos sensíveis ao tempo, como ataques à base, desafios e atividade da guilda.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

O SDK do OneSignal instalado no seu app. Veja Configuração do SDK móvel ou Configuração do SDK web.
Um external_id definido para cada usuário para que você possa segmentá-los pelo seu próprio identificador. Veja Usuários e Aliases.
Um backend que possa detectar ações sociais e chamar a API do OneSignal. Veja Visão geral da REST API.
Modelos criados no painel se você planeja usar custom_data para personalização. Um template_id é obrigatório para usar custom_data.

Mantenha os payloads de custom_data abaixo de 2KB. O campo custom_data tem um limite de tamanho rígido. Enviar payloads grandes — listas completas de conversas, arrays de ranking, imagens em base64 ou HTML — arrisca truncamento ou rejeição. Para conteúdo rico, passe um identificador (por exemplo, digest_id ou summary_url) e faça com que o dispositivo do destinatário busque o payload completo do seu backend ao tocar. Veja Personalize mensagens com custom_data da API para detalhes do limite de tamanho e padrões de iteração de arrays.

Envie uma notificação push quando um usuário estiver envolvido em uma ação social. Use custom_data para injetar o nome do remetente, o avatar e o contexto relevante na mensagem no momento do envio. Nenhum dado é armazenado no OneSignal.

Ações sociais comuns

Ação	Notificação de exemplo
Curtida	”Anna curtiu sua foto.”
Comentário	”Leo respondeu: ‘Parece incrível!’”
Menção	”Sara mencionou você em um comentário.”
Marcação	”James marcou você em uma postagem.”
Seguida	”Maya começou a seguir você.”
Convite	”Ben convidou você para o evento.”
Compartilhamento	”Alex compartilhou ‘Álbum Havaí’ com você.”

Configuração

Detecte a ação no seu backend

Quando uma ação social ocorre, seu backend identifica o remetente e o destinatário, além de qualquer contexto relevante, como o ID da postagem ou o conteúdo:

JSON

{
  "action": "like",
  "sender_id": "user_b",
  "sender_name": "Anna",
  "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
  "recipient_id": "user_a",
  "post_id": "xyz789",
  "post_title": "My Hawaii trip"
}

Crie um modelo de push

No painel, vá para Messages > Templates > New Push Template. Use a sintaxe Liquid para referenciar os campos de custom_data:Título:

Liquid

{{ message.custom_data.sender_name | default: "Someone" }}

Mensagem:

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} liked your post "{{ message.custom_data.post_title | default: "your post" }}".

Imagem (opcional, exibe o avatar do remetente):

Liquid

{{ message.custom_data.sender_avatar }}

Salve o modelo e anote seu template_id.

Chame a API Create Message

Do seu backend, envie a notificação ao destinatário:

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
    "post_title": "My Hawaii trip",
    "post_id": "xyz789"
  },
  "url": "yourapp://posts/xyz789"
}

O OneSignal renderiza o modelo no momento do envio usando os valores de custom_data. O nome e o avatar do remetente aparecem na notificação sem serem armazenados no OneSignal.

Opcional: adicione fallbacks de email e SMS

Para alcançar usuários que têm push desabilitado ou cuja notificação não foi entregue, veja Fallbacks de email e SMS abaixo.

Use filtros | default: em todo placeholder Liquid para que a mensagem continue legível se um campo estiver ausente. Por exemplo: {{ message.custom_data.sender_name | default: "Someone" }}. Veja Usando a sintaxe Liquid para mais filtros.

Requisitos de URL de avatar e imagem. A URL de sender_avatar (e qualquer outra imagem de notificação) deve ser:

HTTPS — o iOS rejeita URLs HTTP.
Acessível publicamente — o APNs e o FCM não podem enviar requisições autenticadas.
Abaixo de ~1 MB — o limite do iOS é 10 MB, mas janelas práticas de entrega favorecem assets menores.
Servida com o header Content-Type correto — image/jpeg, image/png, etc.

Hospedar em um CDN com headers de cache é a configuração mais segura.

Limite ações de alto volume

Uma postagem viral pode gerar milhares de eventos de like por segundo. Não envie um push para cada um — isso inunda o destinatário e faz seu app ser silenciado ou desinstalado. O padrão:

Acumule contagens no seu backend (por exemplo, um contador Redis com chave por destinatário + postagem).
Após uma janela de silêncio (10 minutos é um padrão razoável), envie um único push de resumo: “12 pessoas curtiram sua postagem.”
Se mais curtidas chegarem após o resumo, inicie uma nova janela — não envie outro push imediatamente.

A mesma lógica se aplica a comentários, seguidas e reações. Veja Throttling para limites de taxa do lado do OneSignal caso seu backend não possa fazer debounce.

Mensagens diretas (usuário para usuário)

Notifique um usuário quando ele receber uma nova mensagem direta e leve-o via deep link diretamente para a conversa.

Envie um push apenas quando o destinatário não estiver ativamente no chat. Notificar alguém que já está lendo a conversa cria uma experiência ruim. Use a lógica do próprio app para verificar se o destinatário está atualmente ativo antes de acionar uma notificação. O OneSignal não rastreia se um usuário está usando seu app no momento.

Configuração

Detecte quando uma mensagem é enviada e verifique a atividade

Quando o Usuário A envia uma mensagem para o Usuário B, verifique se o Usuário B está atualmente ativo naquela conversa. Se o Usuário B estiver offline ou fora da conversa, prossiga com o envio de um push.

Evite enviar um push por mensagem

Se o Usuário A enviar várias mensagens em sequência, aguarde um curto período após a última mensagem antes de acionar uma notificação. Veja como fazer isso no seu backend:

Quando a primeira mensagem chegar, inicie um timer (por exemplo, 60 segundos).
Se outra mensagem chegar antes que o timer termine, reinicie-o.
Quando o timer terminar sem novas mensagens, envie um único push resumindo a contagem de não lidas.

O OneSignal não consolida múltiplas chamadas de API automaticamente, então, se você chamar a API cinco vezes, cinco notificações são enviadas.

Envie a notificação push

Envie um push para o Usuário B com um deep link para a conversa:

JSON

{
  "app_id": "YOUR_APP_ID",
  "headings": { "en": "New message" },
  "contents": { "en": "Anna: 'Hey, you around?'" },
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "url": "yourapp://chat/chat_1234",
  "data": {
    "click_action": "open_chat",
    "conversation_id": "chat_1234",
    "sender_id": "user_a_id"
  }
}

Seu app lê data.conversation_id na abertura da notificação e navega para a tela correta. Veja Deep linking para a configuração específica de cada plataforma.

Opcional: adicione fallbacks de email e SMS

Para alcançar usuários que têm push desabilitado ou cuja notificação não foi entregue, veja Fallbacks de email e SMS abaixo.

Agrupe notificações por conversa nativamente. O debounce no backend reduz quantas notificações são disparadas, mas o iOS e o Android também podem colapsar visualmente múltiplas notificações em uma única thread. Defina um identificador de thread ou de colapso (por exemplo, o conversation_id) para que o SO agrupe mensagens do mesmo chat. Veja Agrupamento de notificações.

Atualize a contagem do badge a cada nova mensagem. A maioria dos apps de chat quer que o badge do iOS/Android reflita o total de mensagens não lidas em todas as conversas. Passe a contagem de não lidas via API em cada push para que o badge permaneça preciso mesmo quando um usuário limpar uma notificação, mas tiver outras pendentes. Veja Badges.

Privacidade na tela de bloqueio. O iOS mostra o conteúdo da notificação na tela de bloqueio por padrão — incluindo a prévia da mensagem (“Anna: ‘Hey, you around?’”). Para apps de mensagens com conteúdo sensível (saúde, finanças, relacionamentos, profissional), considere enviar uma prévia genérica (“Nova mensagem de Anna”) e deixe os usuários optarem por prévias completas nas configurações do seu app.

Jogos: alertas competitivos e sociais

Jogos competitivos se beneficiam de alertas sensíveis ao tempo que criam urgência. Use custom_data para tornar essas notificações específicas e pessoais. Uma notificação que nomeia o atacante ou mostra contagens exatas de recursos é muito mais atraente do que um alerta genérico.

Eventos competitivos comuns

Evento	Notificação de exemplo
Ataque à base	”Sua vila está sob ataque! Orca está saqueando sua base.”
Desafio	”DragonSlayer99 desafiou você para um duelo ranqueado. Você tem 24h para responder.”
Ranking	”Você foi eliminado do top 10. Orca acabou de ultrapassar você em #8.”
Evento de guilda	”A guerra de guilda começa em 30 minutos. BladeClan está contando com você!”
Convite de clã	”DragonSlayer99 convidou você a entrar no BladeClan.”
Recurso pronto	”Suas tropas estão treinadas e prontas para o combate.”

Configuração

Detecte o evento do jogo no seu backend

Quando um evento competitivo ocorre, o backend do seu jogo identifica o jogador afetado e captura o contexto relevante:

JSON

{
  "event": "base_attack",
  "attacker_id": "user_orca",
  "attacker_name": "Orca",
  "recipient_id": "user_dragon",
  "resources_at_risk": {
    "gold": 12400,
    "elixir": 8200
  }
}

Crie um modelo de push

No painel, crie um Modelo de Push com referências Liquid:Título:

Liquid

⚔️ Your village is under attack!

Mensagem:

Liquid

{{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. You're at risk of losing {{ message.custom_data.gold | default: "0" }} gold and {{ message.custom_data.elixir | default: "0" }} elixir.

Salve o modelo e anote seu template_id.

Envie a notificação

Chame a API Create Message a partir do backend do seu jogo:

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "attacker_name": "Orca",
    "gold": "12400",
    "elixir": "8200"
  },
  "url": "yourgame://base/defend",
  "data": {
    "event": "base_attack",
    "attacker_id": "user_orca"
  }
}

A url leva o jogador via deep link diretamente para a tela de defesa. O objeto data passa o contexto ao handler de notificações do seu app para que ele possa carregar o estado de batalha correto.

Opcional: adicione fallbacks de email e SMS

Para alcançar jogadores que têm push desabilitado ou cuja notificação não foi entregue, veja Fallbacks de email e SMS abaixo.

Respeite horários de silêncio para alertas não urgentes. Pushes de ataque à base às 3h da manhã no horário local são um conhecido motivador de opt-outs. Divida seus alertas de jogos em dois níveis:

Críticos em relação ao tempo (guerra de guilda começando em 30 minutos, base sob ataque agora) — envie imediatamente, independentemente do horário local.
Não críticos em relação ao tempo (tropas prontas, recompensa diária disponível, resumo semanal) — use Entrega inteligente ou Horário personalizado por fuso horário para que cheguem em horários de vigília no fuso horário local do jogador.

A maioria dos opt-outs de alertas de jogos vem da segunda categoria sendo enviada na hora errada, não da primeira categoria ser frequente demais.

Considere Live Activities para eventos em andamento. Para partidas, raids ou eventos ao vivo em andamento no iOS 16.1+, uma Live Activity na tela de bloqueio e na Dynamic Island costuma ser uma experiência melhor do que notificações push repetidas atualizando o mesmo contexto. Use Live Activities para o estado ao vivo (“23 minutos restantes, você está em #4”) e reserve o push para momentos de marco ou conclusão.

Mais exemplos de alertas de jogos

Ultrapassagem no ranking
Evento de guilda
Convite de desafio

Mensagem do modelo:

Liquid

{{ message.custom_data.overtaker_name | default: "Another player" }} just passed you. You dropped from #{{ message.custom_data.previous_rank }} to #{{ message.custom_data.current_rank }} on the leaderboard.

Requisição de API:

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "overtaker_name": "Orca",
    "previous_rank": "8",
    "current_rank": "9"
  },
  "url": "yourgame://leaderboard"
}

Envie para todos os membros da guilda simultaneamente passando múltiplos valores de external_id. Cada um recebe a mesma mensagem.Mensagem do modelo:

Liquid

Guild war alert! {{ message.custom_data.guild_name | default: "Your guild" }} clashes in {{ message.custom_data.minutes_until | default: "30" }} minutes. Get in position.

Requisição de API:

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon", "user_orca", "user_shadow"]
  },
  "custom_data": {
    "guild_name": "BladeClan",
    "minutes_until": "30"
  },
  "url": "yourgame://guild/war"
}

Mensagem do modelo:

Liquid

{{ message.custom_data.challenger_name | default: "A player" }} challenged you to a {{ message.custom_data.game_mode | default: "duel" }}. You have {{ message.custom_data.hours_to_respond | default: "24" }} hours to accept.

Requisição de API:

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "challenger_name": "DragonSlayer99",
    "game_mode": "ranked duel",
    "hours_to_respond": "24"
  },
  "url": "yourgame://challenges/incoming",
  "data": {
    "challenge_id": "chal_9876",
    "challenger_id": "user_dragonslayer99"
  }
}

Fallbacks de email e SMS

Adicione um fallback de email ou SMS a qualquer tipo de notificação para alcançar usuários que têm push desabilitado ou cuja notificação não foi entregue. Use a API View Message para verificar um recebimento confirmado ou clique. Se nenhum for registrado dentro da sua janela de atraso, envie um follow-up usando a mesma abordagem de custom_data com um modelo de Email ou SMS.

Atividade socialMelhor para ações de alto valor, como menções e respostas diretas.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "sender_avatar": "https://cdn.yourapp.com/avatars/anna.jpg",
    "action": "liked your post",
    "post_title": "My Hawaii trip",
    "post_url": "https://yourapp.com/posts/xyz789"
  }
}

Exemplo de modelo de email (assunto):

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} {{ message.custom_data.action | default: "interacted with your post" }}

Mensagens diretasMelhor como um resumo diário de conversas não lidas em vez de alertas por mensagem.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "custom_data": {
    "unread_count": "3",
    "conversations": [
      { "sender_name": "Anna", "preview": "Hey, you around?", "url": "https://yourapp.com/chat/chat_1234" },
      { "sender_name": "Leo", "preview": "Did you see this?", "url": "https://yourapp.com/chat/chat_5678" }
    ]
  }
}

Exemplo de modelo de email (assunto):

Liquid

You have {{ message.custom_data.unread_count | default: "new" }} unread message{% if message.custom_data.unread_count != "1" %}s{% endif %}

Exemplo de modelo de email (corpo, iterando sobre o array de conversas):

Liquid

<h2>You have {{ message.custom_data.unread_count }} unread messages</h2>
<ul>
  {% for conversation in message.custom_data.conversations %}
    <li>
      <strong>{{ conversation.sender_name }}:</strong>
      "{{ conversation.preview }}"
      <a href="{{ conversation.url }}">Open</a>
    </li>
  {% endfor %}
</ul>

Veja Personalize mensagens com custom_data da API para a referência completa de iteração de arrays, incluindo objetos aninhados e renderização condicional.JogosMelhor para resumos não urgentes, como resumos semanais de ranking, resultados de guerra de guilda ou desbloqueio de marcos.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_EMAIL_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "player_name": "DragonSlayer99",
    "rank": "7",
    "rank_change": "+3",
    "top_players": [
      { "name": "Orca", "score": "48200" },
      { "name": "Shadow", "score": "45100" },
      { "name": "DragonSlayer99", "score": "43800" }
    ],
    "summary_url": "https://yourgame.com/rankings/weekly"
  }
}

Exemplo de modelo de email (assunto):

Liquid

Your weekly rankings: #{{ message.custom_data.rank }} ({{ message.custom_data.rank_change }} this week)

Atividade socialMelhor para ações de alta importância, como menções e respostas diretas, não curtidas ou seguidas rotineiras.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_a"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "post_title": "My Hawaii trip",
    "post_url": "https://yourapp.com/posts/xyz789"
  }
}

Exemplo de modelo de SMS:

Liquid

{{ message.custom_data.sender_name | default: "Someone" }} mentioned you in "{{ message.custom_data.post_title | default: "a post" }}". Tap to reply: {{ message.custom_data.post_url }}

Mensagens diretasMelhor para mensagens perdidas individuais em vez de sequências de mensagens em massa.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_b_id"]
  },
  "custom_data": {
    "sender_name": "Anna",
    "message_preview": "Hey, you around?",
    "conversation_url": "https://yourapp.com/chat/chat_1234"
  }
}

Exemplo de modelo de SMS:

Liquid

New message from {{ message.custom_data.sender_name | default: "a user" }}: "{{ message.custom_data.message_preview }}". Reply in the app: {{ message.custom_data.conversation_url }}

JogosMelhor para eventos críticos em relação ao tempo, como ataques à base, em que o jogador precisa agir imediatamente.

JSON

{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_SMS_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user_dragon"]
  },
  "custom_data": {
    "attacker_name": "Orca",
    "gold": "12400",
    "game_url": "https://yourgame.com/base/defend"
  }
}

Exemplo de modelo de SMS:

Liquid

⚔️ ATTACK! {{ message.custom_data.attacker_name | default: "An enemy" }} is raiding your base. {{ message.custom_data.gold | default: "0" }} gold at risk. Defend now: {{ message.custom_data.game_url }}

Dê aos usuários controle sobre suas preferências de fallback. Um opt-in como “Notifique-me por SMS se eu perder uma mensagem” ajuda a evitar mensagens indesejadas para usuários que intencionalmente têm push desabilitado.

FAQ

O OneSignal pode enviar notificações em tempo real, como um app de chat?

Não. As notificações push são entregues pela infraestrutura da Apple (APNs) e do Google (FCM), o que introduz tempos de entrega variáveis e nenhuma garantia de entrega. Use a camada de mensagens existente do seu app para comunicação em tempo real dentro do app e use o OneSignal como fallback quando o destinatário não estiver ativamente no app.

Como evito notificar um usuário que já está no app?

O OneSignal não rastreia se um usuário está ativo no seu app no momento. Sua própria lógica de backend deve determinar se a notificação deve ser acionada. Chame a API do OneSignal apenas quando você tiver confirmado que o destinatário está offline ou fora da tela relevante.

Como evito múltiplas notificações de sequências rápidas de mensagens?

Adicione um pequeno atraso no seu backend antes de enviar uma notificação. Quando a primeira mensagem chegar, inicie um timer. Se outra mensagem chegar antes que ele termine, reinicie-o. Quando o timer terminar, envie um único push com a contagem de não lidas. O OneSignal não consolida múltiplas chamadas de API automaticamente, então, se você chamar a API cinco vezes, cinco notificações são enviadas.

O `custom_data` é salvo no perfil do usuário depois que a mensagem é enviada?

Não. O custom_data é efêmero e existe apenas durante a requisição de API, usado para renderizar o modelo no momento do envio. Ele não é armazenado no OneSignal e não pode ser reutilizado em mensagens futuras ou Journeys. Para dados de usuário persistentes, use Tags.

Posso segmentar múltiplos destinatários em uma única chamada de API?

Sim. Passe múltiplos valores de external_id no array include_aliases. Se cada destinatário precisar de conteúdo personalizado diferente (por exemplo, nomes de atacantes diferentes), use o padrão de personalização em massa no custom_data. Veja Personalize mensagens com custom_data da API para a abordagem completa. O limite exato de destinatários por chamada e os limites de taxa estão documentados na referência da API Create Message — para audiências muito grandes, a segmentação baseada em segmentos é mais eficiente do que passar milhares de valores de external_id por chamada.

Preciso localizar mensagens para usuários internacionais?

Sim, para qualquer audiência que abranja vários idiomas. Os campos headings e contents aceitam múltiplos códigos de idioma (por exemplo, { "en": "...", "es": "...", "fr": "..." }) e o OneSignal seleciona a variante correta com base no idioma de cada assinatura. O mesmo padrão se aplica aos campos de modelos. Veja Mensagens multilíngues para a referência completa, incluindo o comportamento de idioma de fallback.

Páginas relacionadas

Personalize mensagens com custom_data da API

Injete dados dinâmicos e específicos da mensagem em modelos usando custom_data e a sintaxe Liquid.

Personalização de mensagens

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

Deep linking

Direcione usuários para uma tela específica do seu app quando eles tocarem em uma notificação.

Criar um Feed de Atividades

Exiba um histórico de alertas sociais dentro do seu app usando a caixa de entrada de notificações do OneSignal.

Modelos

Crie e gerencie modelos de mensagens reutilizáveis para push, email e SMS.

API Create Message

Referência completa da API para enviar mensagens com custom_data, segmentação e todos os campos disponíveis.

Tutoriais

Por setor

Aumentar a engajamento e a retenção

Entregar mensagens críticas ou de alta prioridade

Aprimorar o targeting e a personalização

Aprimorar a experiência do usuário e o onboarding

Atividade social