Referência de payload

Referência para a mensagem Payload usada por Notify ao enviar por qualquer canal que não seja e-mail (push, SMS, Telegram, Kakao, LINE, WhatsApp).

Payload

preset (string): código do preset a ser aplicado a esta mensagem.
content (LocalizedContent): conteúdo da mensagem. Mutuamente exclusivo com silent.
silent (bool): envia um push silencioso (apenas dados). Mutuamente exclusivo com content.
custom_data (objeto): JSON de formato livre encaminhado para o SDK do cliente como o parâmetro u.
open_action (OpenAction): ação acionada quando o usuário abre a notificação.
open_actions (map<Platform, OpenAction>): substituição por plataforma de open_action. A chave é um valor numérico do enum Platform.
voip_push (bool): notificação VoIP do iOS.

LocalizedContent

Mapeia o código de localidade para o conteúdo por plataforma. As chaves são códigos de duas letras ISO 639-1 (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.

{
  "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:

Correspondência exata com o idioma do dispositivo.
Chave "default".
Chave "en".
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ê visa.

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

Campos de push comuns

Esses 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 (duração, 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 (objeto): substituições brutas de payload específicas da plataforma.
inbox (Inbox): entrada na Message Inbox.

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.

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): prioridade na bandeja.
group_id (string): chave de grupo da 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.

macOS (`mac_os`)

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

Amazon (`amazon`)

Usa os campos de push comuns mais custom_icon e priority (NotificationPriority).

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 de Push Web.

Chrome (`chrome`)

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

Firefox (`firefox`)

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

Windows (`windows`)

O Windows usa uma forma diferente:

{
  "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.

Kakao (`kakao`)

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

LINE (`line`)

content (string): corpo de texto simples.
template (string): código de um modelo LINE configurado no Painel de Controle da 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.

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 pelo índice do 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.

SMS

O SMS usa o fluxo de mensagens genérico. O bloco de plataforma sms é reservado. Forneça o texto através do campo comum body em qualquer bloco de plataforma preenchido. O ID do remetente e outras opções do provedor vêm da configuração de SMS do aplicativo. Consulte Configuração de SMS.

OpenAction

Define a ação executada quando o usuário abre a mensagem.

Exatamente um de:

rich_media (RichMedia): abre uma página de Rich Media.
deep_link: abre um deep link: { "code": "flow-code", "params": { "key": "value" } }.
link (Link): abre uma URL.

RichMedia

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

Link

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

shortener é NONE (padrão) ou BITLY.

Inbox

Configura como a mensagem aparece na Message Inbox.

{
  "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 (a mais baixa) a PRIORITY_MAX (a mais alta).

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Exemplo: Enviar um push para um segmento

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

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

Referência de payload

Payload

LocalizedContent

Seleção de localidade para um dispositivo

Campos de push comuns

iOS (ios)

Android (android, huawei_android, baidu_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

WhatsApp (whatsapp)

SMS