# Notificar
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
Cria e agenda uma única mensagem.
## Estrutura da solicitação
O corpo da solicitação é um `NotifyRequest` com exatamente um de dois tipos:
- [`segment`](#notifysegment): segmenta um público por código de segmento, uma expressão [seglang](/pt/developer/api-reference/segmentation-filters-api/segmentation-language/) ou uma expressão de filtro estruturada.
- [`transactional`](#notifytransactional): envia para uma lista explícita de hwids, IDs de usuário, tokens de push ou dispositivos de teste.
```json title="Formato"
{
"segment": { ... } // OU
"transactional": { ... }
}
```
## NotifySegment
Segmenta usuários que correspondem a um segmento de público ou expressão de filtro.
| Campo | Tipo | Descrição |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Quando e como enviar. Obrigatório. |
| `application` | string | [Código do aplicativo](/pt/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array de [`Platform`](#platform-enum) | Plataformas que a mensagem segmenta. |
| `code` | string | [Código do segmento](/pt/developer/api-reference/api-identifiers/#segment--filter-code). Mutuamente exclusivo com `expression` e `filter_expression`. |
| `expression` | string | Expressão [Seglang](/pt/developer/api-reference/segmentation-filters-api/segmentation-language/). |
| `filter_expression` | `FilterExpression` | Expressão de filtro estruturada (avançado). |
| `payload` | [`Payload`](/pt/developer/api-reference/messaging-api-v2/payload-reference/) | Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Mutuamente exclusivo com `email_payload`. |
| `email_payload` | [`EmailPayload`](/pt/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload de e-mail. |
| `campaign` | string | [Código da campanha](/pt/developer/api-reference/api-identifiers/#campaign-code) para atribuir esta mensagem. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Limites de frequência por usuário. |
| `send_rate` | [`SendRate`](#sendrate) | Limitação para o envio. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (padrão) ou `MESSAGE_TYPE_TRANSACTIONAL`. Controla a filtragem do grupo de controle. |
| `dynamic_content_placeholders` | map<string, string> | Substitui placeholders no conteúdo. |
| `meta_data` | object | Metadados de formato livre encaminhados para análises downstream. |
### Exemplo: Enviar para um segmento
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"segment": {
"application": "XXXXX-XXXXX",
"platforms": ["IOS", "ANDROID"],
"code": "active_users",
"payload": {
"content": {
"localized_content": {
"en": {
"ios": { "body": "Hello!" },
"android": { "body": "Hello!" }
}
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_MARKETING"
}
}'
```
## NotifyTransactional
Envia para uma lista explícita de destinatários.
| Campo | Tipo | Descrição |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Obrigatório. |
| `application` | string | [Código do aplicativo](/pt/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array de [`Platform`](#platform-enum) | Plataformas que a mensagem segmenta. |
| `test_devices` | bool | Se `true`, enviar apenas para os dispositivos de teste do aplicativo. |
| `hwids` | `{ "list": [string, ...] }` | Enviar apenas para estes [hwids](/pt/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid). |
| `users` | `{ "list": [string, ...] }` | Enviar apenas para estes [IDs de usuário](/pt/developer/pushwoosh-knowledge-hub/users-userids/). |
| `push_tokens` | `{ "list": [string, ...] }` | Enviar apenas para estes [tokens de push](/pt/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token). |
| `payload` | [`Payload`](/pt/developer/api-reference/messaging-api-v2/payload-reference/) | Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. |
| `email_payload` | [`EmailPayload`](/pt/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload de e-mail. |
| `return_unknown_identifiers` | bool | Quando `true`, a lista `unknown_identifiers` da resposta lista os identificadores que não foram encontrados. |
| `use_latest_user_device` | bool | Aplica-se apenas quando você segmenta `users`. Quando `true`, a mensagem é entregue ao dispositivo mais recentemente ativo de cada usuário — aquele com a última Abertura de Aplicativo — em vez de todos os dispositivos vinculados a esse ID de usuário. O padrão é `false` (enviar para todos os dispositivos). |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | Veja `NotifySegment` acima. |
`test_devices`, `hwids`, `users` e `push_tokens` são mutuamente exclusivos. Exatamente um deve ser definido.
### Exemplo: Transacional por IDs de usuário
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transactional": {
"application": "XXXXX-XXXXX",
"platforms": ["IOS", "ANDROID"],
"users": { "list": ["user-123", "user-456"] },
"payload": {
"content": {
"localized_content": {
"en": { "ios": { "body": "Your order has shipped." } }
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_TRANSACTIONAL",
"return_unknown_identifiers": true,
"use_latest_user_device": true
}
}'
```
## Resposta
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| Campo | Tipo | Descrição |
|---|---|---|
| `message_code` | string | [Código de mensagem](/pt/developer/api-reference/api-identifiers/#message-code) exclusivo. Use-o com [`/getMessageDetails`](/pt/developer/api-reference/messages-api/#getmessagedetails) e endpoints de estatísticas de mensagens. |
| `unknown_identifiers` | array de string | Identificadores não encontrados na conta. Preenchido apenas quando `return_unknown_identifiers: true` foi definido no tipo `transactional`. |
## Tipos compartilhados
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| Campo | Tipo | Descrição |
|---|---|---|
| `at` | timestamp | Tempo de envio absoluto (RFC 3339). Se no passado, a mensagem é enviada imediatamente. Máximo de 14 dias no futuro. |
| `after` | duration | Alternativa para `at`. Enviar após este deslocamento de "agora" (por exemplo, `"3600s"`). |
| `follow_user_timezone` | bool | Quando `true`, cada dispositivo recebe a mensagem em `at` no seu fuso horário local. |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (padrão), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND` ou `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. Significativo apenas quando `follow_user_timezone` é `true`. |
### FrequencyCapping
Limites de frequência por usuário para envios de marketing. Para desativar a limitação, omita `frequency_capping` completamente ou envie `days: 0` junto com `count: 0`.
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, ou `0` para desativar a limitação): janela de retrospectiva. Deve ser enviado junto com `count` — se um for `0`, o outro também deve ser `0`; enviar um como `0` enquanto o outro não for zero retorna `400`.
- `count` (int, 1 ou superior, ou `0` para desativar a limitação): máximo de mensagens permitidas dentro de `days`. Mesma regra de pareamento de `days` acima.
- `exclude` (bool): excluir permanentemente usuários que já atingiram o limite.
- `avoid` (bool): evitar suavemente usuários que já atingiram o limite (eles ainda contam para as análises).
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
Limita o envio. `value` é o número de mensagens por `bucket`; o `bucket` típico é `"1s"`.
### Enum de plataforma
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.
### Enum de tipo de mensagem
- `MESSAGE_TYPE_UNSPECIFIED`: equivalente a `MESSAGE_TYPE_MARKETING`.
- `MESSAGE_TYPE_MARKETING`: sujeito à filtragem do grupo de controle e à limitação de frequência.
- `MESSAGE_TYPE_TRANSACTIONAL`: ignora a filtragem do grupo de controle e a limitação de frequência. Use para confirmações de pedido, OTPs e fluxos críticos semelhantes.
## Relacionado