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, Viber, WhatsApp).

Nota

Para e-mail, consulte a referência de payload de e-mail.

Payload

• preset (string): código do preset de push (formato XXXXX-XXXXX) a ser aplicado a esta mensagem.
• sms_preset (string): código (formato XXXXX-XXXXX) de um preset de SMS salvo. Seu texto por localidade é resolvido no sms.body de cada localidade. Um sms.body em linha para uma determinada localidade substitui o preset para essa localidade. O preset deve pertencer ao mesmo aplicativo 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:

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ê visa.

Bloco de plataforma	Canal
ios	Push iOS
android	Push Android (FCM)
huawei_android	Push Huawei Android
baidu_android	Push Baidu Android
mac_os	Push macOS
amazon	Push Amazon (ADM)
safari	Push web Safari
chrome	Push web Chrome
firefox	Push web Firefox
ie	Push web Internet Explorer
windows	Push 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 SMS

Campos de push comuns

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): ativar ou suprimir 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): entrada da Message Inbox.

{
  "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): cortar 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 APNs. Notificações com o mesmo collapse_id substituem 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 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 modelo de URL do 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 string JSON para o modelo 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 modelo aprovado.
• content_variables (string): associações de variáveis do modelo em 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 modelo 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.

{
  "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<string, string>): associaçõ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:<telefone> (E.164), por exemplo viber:+1234567890.

Texto simples:

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

Modelo 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 24 horas de atendimento ao cliente, aberta por uma mensagem recebida do usuário) e modelos aprovados (necessários para iniciar o contato 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 Meta pré-aprovado (ex. "hello_world"). Obrigatório para iniciar o contato ou para 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 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:

• Em linha — defina sms.body por localidade em localized_content.
• De um preset — defina o sms_preset no nível do payload para o código (formato XXXXX-XXXXX) de um preset de SMS salvo. Seu conteúdo por localidade é resolvido em sms.body para cada localidade que o preset define. Um sms.body em linha para uma localidade substitui o preset para essa localidade, então você pode reutilizar um preset 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." } }
      }
    }
  }
}

MMS

Adicionar subject e file_urls a um bloco sms transforma a mensagem em um MMS. Apenas a AbleMobile possui um endpoint MMS — outros provedores de SMS ignoram ambos os campos e entregam apenas o body em texto simples.

• subject (string): assunto do MMS. Requer pelo menos uma entrada em file_urls — um assunto sem anexos é rejeitado. Até 40 caracteres ASCII, ou 13 caracteres se o assunto contiver caracteres não-ASCII.
• file_urls (array de string): até 3 URLs de anexo. Cada uma deve ser uma URL https absoluta terminando em .jpg ou .gif — .jpeg e .png são rejeitados pela validação, mesmo para um arquivo JPEG ou PNG genuíno, porque o provedor não consegue decodificá-los. Cada arquivo também deve ter 200 KB ou menos; a AbleMobile rejeita todo o envio se algum anexo for mais pesado.
• message_at (int): índice em file_urls (base 0) após o qual o texto do corpo do SMS é mostrado.

subject e file_urls suportam personalização Liquid, assim como body.

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

OpenAction

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

Exatamente um de:

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

{
  "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 — as expressões são resolvidas antes que o deep link seja aberto.

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 exibida 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

Cuidado

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 priority, em vez de retornar um erro.

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