> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactional messages
> Aprenda como enviar mensagens transacionais como OTPs, atualizações de cobrança e lembretes usando a API do OneSignal com dados personalizados via push, email ou SMS.
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](./users), [Subscriptions](./subscriptions) e [Aliases](./aliases) do OneSignal.
* Configure seu [Database, DMP ou CRM para se comunicar com o OneSignal](./database-dmp-crm-integration) ou use uma de nossas [Integrações](./integrations).
* Crie [Templates](./templates) para personalizar suas mensagens.
* Use [Liquid Syntax](./using-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](/reference/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:
```json external_id theme={null}
{
"app_id": "YOUR_APP_ID",
"include_aliases": {"external_id": ["userA", "userB"]},
"contents": {"en": "English Message"},
"target_channel": "push"
}
```
```json custom_alias theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"app_id": "YOUR_APP_ID",
"include_email_tokens": ["user1@email.com", "user2@email.com"],
"email_subject": "Welcome to Cat Facts!",
"email_body": "Welcome to Cat FactsWelcome to Cat Facts
Learn more about everyone's favorite furry companions!
Hi Nick,
Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.
Today's Cat Fact (March 27)
In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.
Show me more Cat Facts
(c) 2018 Cat Facts, inc
Unsubscribe
"
}
```
### 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.
```json theme={null}
{
"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](./templates) via dashboard ou [API Create template](/reference/create-template).
2. Adicione [Liquid Variables](./using-liquid-syntax) (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.
```json theme={null}
{
"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 }}
```
3. Gere o `verification_code` no seu servidor quando o usuário solicitar acesso.
4. Insira o valor do `verification_code` na solicitação da API.
```json theme={null}
{
"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:
```json theme={null}
{
"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
* [Guia Create message](/reference/create-message)
* [Users](./users) e [Aliases](./aliases)
* [Templates](./templates) e [Liquid Syntax](./using-liquid-syntax)
* [Rate Limits](/reference/rate-limits)
***