# Referência de payload

Referência para a mensagem `Payload` usada por [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) ao enviar através de qualquer canal que não seja e-mail (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp).

<Aside type="note">
Para e-mail, consulte a [referência de payload de e-mail](/pt/developer/api-reference/messaging-api-v2/email-payload-reference/).
</Aside>

## Payload

- `preset` (string): código do [preset de push](/pt/product/content/push-presets/) (formato `XXXXX-XXXXX`) a ser aplicado a esta mensagem.
- `sms_preset` (string): código (formato `XXXXX-XXXXX`) de um [preset de SMS](/pt/product/content/sms-presets/) salvo. Seu texto por localidade é resolvido no [`sms.body`](#sms-sms) de cada localidade. Um `sms.body` embutido para uma determinada localidade substitui o preset para essa localidade. O preset deve pertencer à mesma aplicação da mensagem.
- `content` ([`LocalizedContent`](#localizedcontent)): conteúdo da mensagem. Mutuamente exclusivo com `silent`.
- `silent` (bool): envia um push silencioso (apenas dados). Mutuamente exclusivo com `content`.
- `custom_data` (object): JSON de formato livre encaminhado para o SDK do cliente como o parâmetro `u`.
- `open_action` ([`OpenAction`](#openaction)): ação acionada quando o usuário abre a notificação.
- `open_actions` (map&lt;Platform, `OpenAction`&gt;): substituição por plataforma de `open_action`. A chave é um valor numérico do enum `Platform`.
- `voip_push` (bool): notificação VoIP do iOS.

```json
{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}
```

## LocalizedContent

Mapeia o código de localidade → conteúdo por plataforma. As chaves são códigos de duas letras [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) (por exemplo, `"en"`, `"es"`) mais a chave especial `"default"` para uma tradução genérica. As exceções à ISO 639-1 são `"zh-Hant"` e `"zh-Hans"` para chinês tradicional e simplificado.

```json
{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}
```

### Seleção de localidade para um dispositivo

O conteúdo entregue a um dispositivo é escolhido nesta ordem:

1. Correspondência exata com o idioma do dispositivo.
2. Chave `"default"`.
3. Chave `"en"`.
4. Qualquer outra localidade presente no mapa.

Forneça pelo menos um de `"default"` ou `"en"` para que cada dispositivo tenha um fallback determinístico. Se você não espera variantes por localidade, envie apenas `"default"`.

Cada entrada de localidade é um objeto `Content` com blocos opcionais por plataforma. Preencha apenas as plataformas que você segmenta.

| Bloco de plataforma | Canal |
|---|---|
| `ios` | Push do iOS |
| `android` | Push do Android (FCM) |
| `huawei_android` | Push do Huawei Android |
| `baidu_android` | Push do Baidu Android |
| `mac_os` | Push do macOS |
| `amazon` | Push da Amazon (ADM) |
| `safari` | Push web do Safari |
| `chrome` | Push web do Chrome |
| `firefox` | Push web do Firefox |
| `ie` | Push web do Internet Explorer |
| `windows` | Push do Windows (tile / toast / badge) |
| `telegram` | Mensagem do Telegram |
| `kakao` | Mensagem do Kakao |
| `line` | Mensagem do LINE |
| `viber` | Mensagem do Viber |
| `whatsapp` | Mensagem do WhatsApp |
| `sms` | Mensagem de SMS |

## Campos comuns de push

Estes campos são compartilhados pelos blocos `ios`, `android`, `huawei_android`, `baidu_android`, `mac_os`, `amazon`, `safari`, `chrome` e `firefox` (o suporte varia. Campos não utilizados são ignorados pela plataforma relevante).

- `title` (string): título da notificação.
- `body` (string): corpo da notificação.
- `time_to_live` (duration, ex. `"3600s"`): por quanto tempo o servidor de push deve reter a notificação para um dispositivo offline.
- `sound` (string): nome do arquivo de som.
- `sound_enabled` (bool): ativa ou suprime o som.
- `badges` (string): contagem de emblemas (iOS) ou análogo.
- `root_params` (object): substituições brutas de payload específicas da plataforma.
- `inbox` ([`Inbox`](#inbox)): entrada da [Caixa de Entrada de Mensagens](/pt/developer/guides/message-inbox/mobile-message-inbox/).

```json
{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}
```

## iOS (`ios`)

- `subtitle` (string): subtítulo da notificação do iOS.
- `is_critical` (bool): alerta crítico (requer autorização).
- `attachment` (string): URL de um anexo de mídia.
- `thread_id` (string): identificador de thread para notificações agrupadas.
- `trim_content` (bool): corta o conteúdo para caber.
- `category_id` (string): identificador `UNNotificationCategory` para ações interativas.
- `interruption_level` (string): `passive`, `active`, `time-sensitive` ou `critical`.
- `collapse_id` (string): identificador de colapso do APNs. Notificações com o mesmo `collapse_id` substituem umas às outras no dispositivo.

```json
{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}
```

## Android (`android`, `huawei_android`, `baidu_android`)

- `icon` (string): ícone pequeno da notificação.
- `banner` (string): URL da imagem grande.
- `delivery_priority` (`NORMAL` | `HIGH`): prioridade de entrega do FCM.
- `vibration` (bool): vibração ao receber.
- `led_color` (string, hex): cor do LED da notificação.
- `icon_background_color` (string, hex): cor de fundo do ícone.
- `show_on_lockscreen` (bool): mostrar na tela de bloqueio.
- `custom_icon` (string): URL de um ícone personalizado.
- `priority` ([`NotificationPriority`](#notificationpriority-enum)): prioridade na bandeja.
- `group_id` (string): chave do grupo de notificação.
- `collapse_key` (string): chave de colapso do FCM. Notificações com a mesma `collapse_key` substituem umas às outras enquanto o dispositivo está offline.

```json
{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}
```

## macOS (`mac_os`)

Usa os campos comuns de push mais `subtitle` e `action` (URL aberta quando o usuário clica na notificação).

```json
{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}
```

## Amazon (`amazon`)

Usa os campos comuns de push mais `custom_icon` e `priority` ([`NotificationPriority`](#notificationpriority-enum)).

```json
{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}
```

## Safari (`safari`)

- `action` (string): URL aberta quando o usuário clica na notificação.
- `url_arguments` (array de string): argumentos de URL do Safari substituídos no modelo de URL do Web Push.

```json
{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}
```

## Chrome (`chrome`)

- `icon`, `image` (string): URLs do ícone pequeno e da imagem grande.
- `duration` (duration): temporizador de fechamento automático.
- `button_text1` / `button_url1`, `button_text2` / `button_url2`: até dois botões de ação.

```json
{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}
```

## Firefox (`firefox`)

Usa apenas `title`, `body`, `icon`, `root_params` e `inbox`.

```json
{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}
```

## Windows (`windows`)

O Windows usa uma forma diferente:

```json
{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}
```

- `type` é `TILE`, `TOAST` ou `BADGE`.
- `template` (estruturado) ou `raw` (`{ "content": "<raw xml>" }`) — exatamente um.

## Telegram (`telegram`)

- `body` (string): texto da mensagem.
- `content_variables` (string): variáveis em formato de string JSON para o modelo do lado do bot.

```json
{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## Kakao (`kakao`)

- `content` (string): conteúdo da mensagem.
- `template` (string): código do modelo aprovado.
- `content_variables` (string): vinculações de variáveis do modelo em formato de string JSON.

```json
{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## LINE (`line`)

- `content` (string): corpo de texto simples.
- `template` (string): código de um modelo do LINE configurado no Painel de Controle do Pushwoosh (usado para enviar mensagens de imagem, carrossel ou flex). Para conteúdo rico, pré-configure o modelo no Painel de Controle e referencie-o aqui.

Pelo menos um de `content` ou `template` deve ser definido.

```json
{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}
```

## Viber (`viber`)

Uma mensagem do Viber é um corpo de texto livre ou um modelo transacional pré-aprovado (Omni Messaging / MStat) referenciado por id e idioma.

- `body` (string): mensagem de texto simples. Obrigatório quando `template_id` não está definido.
- `template_id` (string): id de um modelo transacional pré-aprovado. Quando definido, tem precedência sobre `body`.
- `template_lang` (string): localidade do modelo. Obrigatório quando `template_id` está definido.
- `template_params` (map&lt;string, string&gt;): vinculações de chave/valor substituídas no modelo, ex. `{ "name": "John", "code": "123456" }`.
- `all_devices` (bool): `false` (padrão) entrega apenas ao dispositivo principal do usuário; `true` entrega a todos os dispositivos do usuário.

Pelo menos um de `body` ou `template_id` deve ser definido. Quando `template_id` é definido, `template_lang` é obrigatório.

Enderece os destinatários do Viber como hwids no formato `viber:<phone>` (E.164), por exemplo `viber:+1234567890`.

Texto simples:

```json
{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}
```

Modelo transacional:

```json
{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}
```

## WhatsApp (`whatsapp`)

As mensagens do WhatsApp passam pela Meta e estão sujeitas às regras de mensagens da Meta. A principal divisão é entre texto de formato livre (entregue apenas dentro da janela de atendimento ao cliente de 24 horas aberta por uma mensagem recebida do usuário) e modelos aprovados (necessários para o início de conversas e para qualquer mensagem fora da janela de 24 horas).

- `content` (string): texto da mensagem de formato livre. Entregue pela Meta apenas dentro da janela de 24 horas.
- `content_id` (string): nome de um modelo pré-aprovado da Meta (ex. `"hello_world"`). Necessário para o início de conversas ou qualquer mensagem fora da janela de 24 horas.
- `language` (string): localidade do modelo que deve corresponder exatamente à localidade aprovada na Meta (ex. `"en_US"`, `"en_GB"`). Só faz sentido junto com `content_id`. Isso é independente da chave `LocalizedContent` externa. A chave externa seleciona o conteúdo para um dispositivo, e `language` seleciona a localidade do modelo da Meta para esse conteúdo.
- `content_variables` (string): objeto JSON mapeando placeholders do corpo, ex. `"{\"1\":\"John\"}"`.
- `button_url_variables` (string): objeto JSON mapeando placeholders de URL de botão com chave por índice de botão, ex. `"{\"0\":\"https://...\"}"`.
- `header_variables` (string): objeto JSON mapeando placeholders de cabeçalho com chave por tipo, ex. `"{\"image\":\"https://...\"}"`.

Pelo menos um de `content` ou `content_id` deve ser definido.

```json
{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}
```

## SMS (`sms`)

O SMS tem seu próprio bloco de plataforma dentro do [`Content`](#localizedcontent) de cada localidade, ao lado de `ios`, `android` e dos outros canais de mensagens.

- `body` (string): texto do SMS para a localidade. Obrigatório quando o bloco `sms` está presente.

Existem duas maneiras de fornecer o texto:

- **Embutido** — defina `sms.body` por localidade em `localized_content`.
- **De um preset** — defina o [`sms_preset`](#payload) no nível do payload para o código (formato `XXXXX-XXXXX`) de um [preset de SMS](/pt/product/content/sms-presets/) salvo. Seu conteúdo por localidade é resolvido em `sms.body` para cada localidade que o preset define. Um `sms.body` embutido para uma localidade substitui o preset para essa localidade, então você pode reutilizar um preset e ainda ajustar idiomas individuais.

```json
{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}
```

## OpenAction
Define a ação realizada quando o usuário abre a mensagem.

Exatamente um de:

- `rich_media` ([`RichMedia`](#richmedia)): abre uma página de [Rich Media](/pt/product/content/in-apps/).
- `deep_link`: abre um deep link: `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)): abre uma URL.

```json
{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}
```

A URL do deeplink e os valores de `params` suportam a sintaxe de [personalização Liquid](/pt/developer/guides/personalization/liquid-templates/) — as expressões são resolvidas antes que o deep link seja aberto.

### RichMedia


```json
{ "code": "XXXXX-XXXXX" }        // por código de Rich Media
{ "url":  "https://..." }        // por URL remota
```

### Link


```json
{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}
```

`shortener` é `NONE` (padrão) ou `BITLY`.

## Inbox

Configura como a mensagem aparece na Caixa de Entrada de Mensagens.

```json
{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}
```

- `image_url` (string): imagem mostrada na entrada da caixa de entrada.
- `expiration_date` (timestamp): quando a entrada é removida da caixa de entrada.

## Enum NotificationPriority
Controla a prioridade da notificação no dispositivo de destino, de `PRIORITY_MIN` (mais baixa) a `PRIORITY_MAX` (mais alta).

- `PRIORITY_UNSPECIFIED`
- `PRIORITY_MIN`
- `PRIORITY_LOW`
- `PRIORITY_DEFAULT`
- `PRIORITY_HIGH`
- `PRIORITY_MAX`

<Aside type="caution">
Sempre envie a `priority` como um dos valores de string acima. A API também aceita os equivalentes numéricos do enum (1-5, correspondendo à ordem acima), mas esse mapeamento é um detalhe interno do protobuf, não um contrato suportado — não confie nele.

Um valor de `priority` não reconhecido (uma string com erro de digitação ou um número fora do intervalo) não é rejeitado: a API o descarta silenciosamente, e a notificação é enviada sem nenhum campo de `priority`, em vez de retornar um erro.
</Aside>

## Exemplo: Enviar um push 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":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## Exemplo: Push 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": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'
```