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).

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 embutido para uma determinada localidade substitui o preset para essa localidade. O preset 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 de localidade → 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ê 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): entrada da 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 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 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.

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

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

{
  "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 formato de 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): vinculações de variáveis do modelo 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 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.

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

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

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

OpenAction

Define a ação realizada 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" } }
  }
}

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

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