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, Facebook Messenger).

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 à mesma aplicação da mensagem.
• content (LocalizedContent): conteúdo da mensagem. Mutuamente exclusivo com silent.
• silent (bool): enviar 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 (mapa<Platform, OpenAction>): substituição por plataforma de open_action. A chave é um valor numérico do enum Platform.
• voip_push (bool): notificação VoIP para 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 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 todo 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 para iOS
android	Push para Android (FCM)
huawei_android	Push para Huawei 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
fb_messenger	Mensagem do Facebook Messenger
sms	Mensagem SMS

Campos de push comuns

Estes campos são compartilhados pelos blocos ios, android, huawei_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, por exemplo, "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 do selo (iOS) ou análogo.
• root_params (objeto): substituições brutas de payload 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 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)

• 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, hexadecimal): cor do LED de notificação.
• icon_background_color (string, hexadecimal): 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 de notificação.
• collapse_key (string): chave de colapso do FCM. Notificações com o mesmo 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 strings): argumentos de URL do Safari substituídos no modelo 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 (duração): 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): vínculos 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 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.

{
  "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 (mapa<string, string>): vínculos de chave/valor substituídos no modelo, por exemplo, { "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 está 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 iniciar conversas e para qualquer mensagem fora da janela de 24 horas).

• content (string): texto de 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 (por exemplo, "hello_world"). Necessário para iniciar conversas ou qualquer mensagem fora da janela de 24 horas.
• language (string): localidade do modelo que deve corresponder exatamente à localidade aprovada na Meta (por exemplo, "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 modelo da Meta para esse conteúdo.
• content_variables (string): objeto JSON mapeando os marcadores de posição do corpo, por exemplo, "{\"1\":\"John\"}".
• button_url_variables (string): objeto JSON mapeando os marcadores de posição de URL de botão, indexados pelo índice do botão, por exemplo, "{\"0\":\"https://...\"}".
• header_variables (string): objeto JSON mapeando os marcadores de posição do cabeçalho, indexados por tipo, por exemplo, "{\"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\"}"
  }
}

Facebook Messenger (fb_messenger)

As mensagens do Facebook Messenger passam pela Meta e estão sujeitas às regras de mensagens da Meta: o conteúdo de formato livre só é entregue dentro da janela de atendimento ao cliente de 24 horas aberta por uma mensagem recebida do usuário. Fora dessa janela, defina message_tag para um dos casos de uso aprovados pela Meta, ou a Meta rejeitará o envio.

• body (string): mensagem de texto simples. O Facebook Messenger não tem suporte para modelos ou botões, então este é o único campo de conteúdo.
• message_tag (string): obrigatório fora da janela de 24 horas. Um de CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT.

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

Cuidado

A Pushwoosh não rastreia independentemente se a janela de 24 horas está aberta. Se a janela estiver fechada e message_tag não for definido, o envio falhará com o erro da API Graph da Meta em vez de um erro de validação do lado da Pushwoosh.

Para este canal, não há um identificador de dispositivo separado: hwid, push_token e user_id resolvem para o mesmo valor, o ID de Escopo de Página (PSID) da Meta do destinatário. Segmente uma conversa específica com qualquer um deles em NotifyTransactional.

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

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:

• 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, para que você possa 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 tem um endpoint de MMS — outros provedores de SMS ignoram ambos os campos e entregam apenas o corpo de texto simples body.

• 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 strings): 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 (inteiro): índice em file_urls (base 0) após o qual o texto do corpo do SMS é exibido.

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 executada 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" }        // pelo código de Rich Media
{ "url":  "https://..." }        // pela 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 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"
    }
  }'