Pular para o conteúdo principal
Enviar mensagens oportunas e personalizadas para indivíduos ou pequenos grupos é fundamental para oferecer uma forte experiência do cliente e manter o engajamento. Mensagens transacionais—como Códigos de Uso Único (OTPs), atualizações de cobrança ou confirmações de atividade—permitem que você compartilhe atualizações significativas e em tempo real do seu servidor. Este guia explica como enviar mensagens transacionais (push, email ou SMS) com a API do OneSignal usando dados personalizados e identificadores de usuário.

​
Casos de uso comuns

Use mensagens transacionais para:
  • Enviar códigos de login e verificação (OTP)
  • Confirmar pedidos, recibos ou mudanças de assinatura
  • Entregar status de cobrança ou alertas de renovação
  • Lembrar usuários sobre compromissos ou prazos
  • Reconhecer ações-chave (ex: cadastros ou compras)

​
Requisitos

Antes de enviar mensagens transacionais, sugerimos revisar os seguintes guias:

​
Identificando usuários

Para segmentar usuários individuais, você deve identificá-los dentro do OneSignal. A abordagem recomendada é definir um External ID, que deve mapear para o identificador de usuário usado em seu banco de dados ou CRM. O OneSignal também suporta até 20 aliases por usuário, permitindo que você associe múltiplos identificadores (por exemplo, other_user_id, facebook_id, etc.) através dos seus sistemas. Para email e SMS, você também pode enviar mensagens diretamente usando o endereço de email ou número de telefone respectivamente.

​
Segmentando usuários

Use a API Create Message para enviar mensagens transacionais através dos canais push, email e SMS segmentando usuários via aliases, endereços de email, números de telefone ou IDs de assinatura.

​
Enviar para aliases (recomendado)

Use include_aliases para segmentar o external_id recomendado ou outros aliases assim: 
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA", "userB"]},
  "contents": {"en": "English Message"},
  "target_channel": "push"
}

​
Enviar para assinaturas

Se você quiser enviar para Subscriptions específicas, você pode usar a propriedade include_subscription_ids. Esta opção não é recomendada porque Users podem ter múltiplas Subscriptions. 
{
  "app_id": "YOUR_APP_ID",
  "include_subscription_ids": ["1dd608f2-c6a1-11e3-851d-000c2940e62c"],
  "contents": { "en": "English Message" }
}

​
Enviar para endereços de email

Se você tem o endereço de email do usuário, você pode enviar emails para eles usando a propriedade include_email_tokens. Quaisquer emails incluídos que não existem dentro do seu app OneSignal criarão automaticamente uma nova assinatura de email. 
{
  "app_id": "YOUR_APP_ID",
  "include_email_tokens": ["user1@email.com", "user2@email.com"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>"
}

​
Enviar para números de telefone

Se você tem o número de telefone do usuário, você pode enviar SMS e MMS usando a propriedade include_phone_numbers. Quaisquer números de telefone incluídos que não existem dentro do seu app OneSignal criarão automaticamente uma nova assinatura de SMS. 
{
  "app_id": "YOUR_APP_ID",
  "include_phone_numbers": ["+15555555555"],
  "contents": { "en": "English Message" }
}

​
Adicionando dados personalizados

Para conteúdo personalizado, passe custom_data específico do usuário para a mensagem usando Templates e sintaxe Liquid. Passos para adicionar dados personalizados:
  1. Crie um Template via dashboard ou API Create template.
  2. Adicione Liquid Variables (por exemplo, {{ message.custom_data.order_id }}) ao seu template.
  3. Referencie o template_id e custom_data dentro da sua chamada da API Create Message.
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "order_id": 123, "currency": "USD", "amount": 25 }
}

​
Exemplo: Código de Uso Único (OTP)

  1. Identifique o usuário usando um alias, email ou número de telefone.
  2. Crie um Template que inclua um código de verificação:
Your verification code is {{ message.custom_data.verification_code }}
  1. Gere o verification_code no seu servidor quando o usuário solicitar acesso.
  2. Insira o valor do verification_code na solicitação da API.
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "verification_code": "123456" }
}
Alternativa: Se você não quiser usar templates e custom_data você pode inserir o valor da variável diretamente na mensagem com concatenação de string. Por exemplo: 
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}

​
Solução de problemas

  • Para include_aliases, o alias deve ser registrado no usuário previamente.
  • Para email/SMS, garanta formatação correta.

​
Recursos adicionais