Referência de payload

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

Payload

preset (string): código da predefinição de push (formato XXXXX-XXXXX) a ser aplicado a esta mensagem.
sms_preset (string): código (formato XXXXX-XXXXX) de uma predefinição de SMS salva. Seu texto por localidade é resolvido no sms.body de cada localidade. Um sms.body embutido para uma determinada localidade substitui a predefinição para essa localidade. A predefinição deve pertencer à mesma aplicação da 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 (object): 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.

{
  "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 da 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 da 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
`viber`	Mensagem do Viber
`whatsapp`	Mensagem do WhatsApp
`sms`	Mensagem de SMS

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 (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 de payload bruto específicas da plataforma.
inbox (Inbox): entrada na Caixa de Entrada de Mensagens.

{
  "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-se umas às outras no dispositivo.

{
  "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): 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-se umas às outras enquanto o dispositivo está offline.

{
  "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 de push comuns mais subtitle e action (URL aberta quando o usuário clica na notificação).

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

Amazon (`amazon`)

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

{
  "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 template de URL de Web Push.

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

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

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

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 template do lado do bot.

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

Kakao (`kakao`)

content (string): conteúdo da mensagem.
template (string): código do template aprovado.
content_variables (string): vínculos de variáveis do template em formato de string 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 template 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 template no Painel de Controle e referencie-o aqui.

Pelo menos um de content ou template deve ser definido.

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

Viber (`viber`)

Uma mensagem do Viber é ou um corpo de texto livre ou um template 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 template transacional pré-aprovado. Quando definido, tem precedência sobre body.
template_lang (string): localidade do template. Obrigatório quando template_id está definido.
template_params (map<string, string>): vínculos de chave/valor substituídos no template, ex. { "name": "John", "code": "123456" }.
all_devices (bool): false (padrão) entrega apenas ao dispositivo primário 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:

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

Template transacional:

{
  "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 templates aprovados (necessários para a iniciação de envio 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 template pré-aprovado da Meta (ex. "hello_world"). Necessário para a iniciação de envio ou qualquer mensagem fora da janela de 24 horas.
language (string): localidade do template que deve corresponder exatamente à localidade aprovada na Meta (ex. "en_US", "en_GB"). Só faz sentido junto com content_id. Isso é independente da chave externa LocalizedContent. A chave externa seleciona o conteúdo para um dispositivo, e language seleciona a localidade do template 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.

{
  "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 de cada localidade, ao lado de ios, android e 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 uma predefinição — defina o sms_preset no nível do payload para o código (formato XXXXX-XXXXX) de uma predefinição de SMS salva. Seu conteúdo por localidade é resolvido em sms.body para cada localidade que a predefinição define. Um sms.body embutido para uma localidade substitui a predefinição para essa localidade, para que você possa reutilizar uma predefinição e ainda ajustar idiomas individuais.

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

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

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 Caixa de Entrada de Mensagens.

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

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)

Viber (viber)

WhatsApp (whatsapp)

SMS (sms)