Transactional messages

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:

Entenda Users, Subscriptions e Aliases do OneSignal.
Configure seu Database, DMP ou CRM para se comunicar com o OneSignal ou use uma de nossas Integrações.
Crie Templates para personalizar suas mensagens.
Use Liquid Syntax para personalizar suas mensagens.

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"
}

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "alias_label": ["alias_id_1", "alias_id_2"] },
  "contents": { "en": "English Message" },
  "target_channel": "email"
}

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:

Crie um Template via dashboard ou API Create template.
Adicione Liquid Variables (por exemplo, {{ message.custom_data.order_id }}) ao seu template.
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)

Identifique o usuário usando um alias, email ou número de telefone.
Crie um Template que inclua um código de verificação:

Your verification code is {{ message.custom_data.verification_code }}

Gere o verification_code no seu servidor quando o usuário solicitar acesso.
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.

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

Transactional messages

Casos de uso comuns

Requisitos

Identificando usuários

Segmentando usuários

Enviar para aliases (recomendado)

Enviar para assinaturas

Enviar para endereços de email

Enviar para números de telefone

Adicionando dados personalizados

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

Solução de problemas

Recursos adicionais

​Casos de uso comuns

​Requisitos

​Identificando usuários

​Segmentando usuários

​Enviar para aliases (recomendado)

​Enviar para assinaturas

​Enviar para endereços de email

​Enviar para números de telefone

​Adicionando dados personalizados

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

​Solução de problemas

​Recursos adicionais

Casos de uso comuns

Requisitos

Identificando usuários

Segmentando usuários

Enviar para aliases (recomendado)

Enviar para assinaturas

Enviar para endereços de email

Enviar para números de telefone

Adicionando dados personalizados

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

Solução de problemas

Recursos adicionais