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

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) para todas as plataformas. Mutuamente exclusivo com content. Para tornar silenciosas apenas algumas plataformas, defina silent dentro de content para iOS ou Android.
custom_data (objeto): JSON de formato livre encaminhado para o SDK do cliente como o parâmetro u. Inteiros muito grandes podem perder precisão, consulte Inteiros grandes em dados personalizados.
custom_data_raw (string): uma string que contém um objeto JSON, encaminhada para o SDK do cliente como o parâmetro u. Os números nela mantêm seu valor exato. Mutuamente exclusivo com um custom_data não vazio. Um valor inválido retorna 400.
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" } }
  }
}

Inteiros grandes em dados personalizados

Inteiros acima de 9007199254740992 perdem precisão em custom_data. Use custom_data_raw para mantê-los exatos.

custom_data é um google.protobuf.Struct (um objeto genérico semelhante a JSON). Ele armazena todo número como double, um número de ponto flutuante de 64 bits que é exato apenas para inteiros até 9007199254740992. Inteiros maiores são arredondados: 5190090000030465245 chega ao dispositivo como 5190090000030465000. Strings não são afetadas.

Para manter esses inteiros exatos, envie em custom_data_raw uma string que contém o objeto JSON:

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

Regras para custom_data_raw:

A string deve conter um objeto JSON. Um array, uma string, null ou JSON inválido retorna 400 (INVALID_ARGUMENT) com uma violação de campo em payload.custom_data_raw.
Se custom_data tiver alguma chave e custom_data_raw estiver definido, a solicitação retorna 400. Um objeto custom_data vazio é ignorado.
Assim como custom_data, ele substitui os dados personalizados salvos no preset de push.
O objeto é convertido de volta para texto JSON antes da entrega. A ordem das chaves não é preservada e os espaços em branco são removidos. Os números mantêm seu valor exato, mas o texto original não é preservado byte a byte.
Em /messaging/v2/notify/batch, um custom_data_raw inválido faz falhar apenas o seu próprio item. Os outros itens são enviados.

Como você envia a solicitação:

REST: nenhuma alteração é necessária para /messaging/v2/notify e /messaging/v2/notify/batch. Se custom_data contiver um inteiro que um double não consegue representar exatamente, a API o mantém sem perda automaticamente. Você ainda pode definir custom_data_raw explicitamente.
gRPC: o próprio cliente constrói o Struct, então a precisão é perdida antes de a solicitação ser enviada. Preencha custom_data_raw em vez de custom_data.

Onde a notificação é entregue:

Android: o SDK passa u para o aplicativo como string por meio de PushMessage.getCustomData(), então todos os dígitos são preservados.
Web push: o Web SDK analisa u com JSON.parse, e todo número em JavaScript é um double. Inteiros grandes são arredondados no navegador independentemente da API, então passe-os como strings.
Windows: o toast recebe os mesmos dados u que as outras plataformas, e inteiros enviados por meio de custom_data_raw chegam exatos.

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

Botões

Cada entrada de idioma também pode conter buttons, até 3 botões de ação exibidos abaixo do push no iOS, Android e Huawei. As demais plataformas os ignoram. Os botões exigem iOS SDK 7.2.10 ou posterior com uma Notification Service Extension, e Android SDK 6.17.0 ou posterior.

Cada PushButton tem estes campos:

id (string): o ID do botão que seu aplicativo recebe ao toque. Até 64 caracteres, sem espaços, único dentro do push. Obrigatório para ACTION_OPEN e ACTION_CUSTOM. Se você o omitir para outras ações, o Pushwoosh define btn_1, btn_2 e assim por diante.
label (string): o texto do botão, de 1 a 64 caracteres.
action (enum): ACTION_OPEN abre o aplicativo, ACTION_URL abre url, ACTION_DEEPLINK abre um deep link, ACTION_CUSTOM passa id para o seu aplicativo, e o seu aplicativo o trata.
url (string): um endereço http ou https absoluto para ACTION_URL, ou um deep link com esquema para ACTION_DEEPLINK.
platform_urls (map): um deep link por plataforma para ACTION_DEEPLINK, com o código da plataforma como chave: 1 iOS, 3 Android, 17 Huawei.
style (enum): STYLE_DEFAULT ou STYLE_DESTRUCTIVE. O estilo destrutivo exibe o botão em vermelho no iOS.

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

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.
silent (bool): enviar o push do iOS como silencioso (apenas dados), enquanto as outras plataformas na mesma mensagem recebem uma notificação comum. É definido dentro de content, portanto funciona junto com ele. Para tornar todas as plataformas silenciosas, use o silent de nível superior, que substitui content. Defina-o em qualquer localidade para aplicá-lo a todas as localidades.

{
  "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.
silent (bool): enviar o push para esta plataforma como silencioso (apenas dados), enquanto as outras plataformas na mesma mensagem recebem uma notificação comum. É definido dentro de content, portanto funciona junto com ele. Para tornar todas as plataformas silenciosas, use o silent de nível superior, que substitui content. Defina-o em qualquer localidade para aplicá-lo a todas as localidades. O bloco baidu_android também aceita silent, com o mesmo comportamento.

{
  "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, opcionalmente com uma imagem e um botão ou com um carrossel, 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, a menos que image esteja definido. Obrigatório com um botão ou um carrossel.
image (string): URL pública da imagem. Ignorado quando template_id está definido.
button_caption (string): texto do botão, até 30 caracteres. Defina junto com button_action. Requer body. Ignorado quando template_id está definido.
button_action (string): link do botão: uma URL http:// ou https://, um deep link viber:// ou um token do Omni como {lp-100} (um placeholder de link de rastreamento que o Omni Messaging resolve no momento do envio). Defina junto com button_caption.
carousel (objeto): de 2 a 5 cards deslizáveis exibidos abaixo de body. Não pode ser combinado com image, button_caption, button_action ou template_id. Consulte Carrossel.
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, image 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
  }
}

Carrossel

carousel.items contém de 2 a 5 cards. Para configurar um carrossel em uma journey, consulte Enviar um carrossel. Cada card tem estes campos:

title (string): título do card, de 2 a 38 caracteres. Obrigatório.
image (string): URL pública da imagem http:// ou https://. Obrigatório.
primary_button (objeto): botão principal. Obrigatório.
secondary_button (objeto): segundo botão. Opcional.

Cada botão tem dois campos, e ambos são obrigatórios quando o botão está presente:

caption (string): texto do botão, até 10 caracteres para primary_button e até 12 para secondary_button.
action (string): link do botão: uma URL com esquema (http://, https://, viber://) ou um token do Omni como {lp-100}, os mesmos valores de button_action.

Uma solicitação que viola qualquer uma dessas regras é rejeitada com INVALID_ARGUMENT. O detalhe google.rpc.BadRequest indica o campo, por exemplo viber.carousel.items[0].title.

Exemplo:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

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. Obrigatório, a menos que message esteja definido.
message (string): um objeto message completo da Meta Send API como string JSON, com texto, anexos, modelos ou respostas rápidas. Quando definido, o Pushwoosh o envia em vez de body.
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"
  }
}

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

RCS

Adicionar rcs a um bloco sms envia um modelo de conteúdo da Twilio por RCS (Rich Communication Services) em vez de body. A Twilio entrega o modelo como uma mensagem RCS e, como alternativa, envia um SMS criado a partir do tipo twilio/text do modelo, não a partir de body. Um modelo sem o tipo twilio/text chega apenas a telefones compatíveis com RCS.

rcs.content_sid (string): SID do modelo de conteúdo da Twilio, HX seguido de 32 caracteres hexadecimais. Obtenha-o em ListRcsTemplates ou no Twilio Console.
rcs.content_variables (string): objeto JSON com as variáveis do modelo, serializado como string, por exemplo "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}". Os valores suportam tags e personalização Liquid. Uma variável que você omitir recebe o valor padrão do modelo.

body continua obrigatório em um bloco sms com rcs.

A solicitação é rejeitada, a menos que a aplicação envie SMS pela Twilio com seus próprios Account SID, Auth token e Messaging Service SID definidos na configuração da plataforma SMS. Uma aplicação que usa credenciais da Twilio fornecidas pela Pushwoosh não pode enviar RCS.

Um preset de SMS pode conter um modelo por localidade. Com sms_preset no payload, o modelo do preset é usado para toda localidade em que a solicitação não traz seu próprio rcs.content_sid.

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

Listar modelos RCS

ListRcsTemplates retorna os modelos de conteúdo da Twilio da aplicação que podem ser enviados por RCS, lidos com as próprias credenciais da Twilio da aplicação.

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (string, query): código da aplicação, formato XXXXX-XXXXX.

A resposta contém um array templates. Apenas modelos com pelo menos um tipo de conteúdo RCS são listados: twilio/card, twilio/carousel, twilio/quick-reply, twilio/call-to-action ou twilio/media.

Campo	Tipo	Descrição
`content_sid`	string	SID do modelo, o valor para `rcs.content_sid`.
`friendly_name`	string	Nome do modelo na Twilio.
`language`	string	Código de idioma do modelo.
`types`	array de strings	Tipos de conteúdo da Twilio que o modelo define, por exemplo `twilio/card` e `twilio/text`.
`variables`	objeto	Variáveis do modelo com seus valores padrão.
`has_sms_fallback`	boolean	`true` quando o modelo tem o tipo `twilio/text`, o SMS que um telefone sem RCS recebe.

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

ListRcsTemplates retorna estes erros:

Status HTTP	Causa
`400 Bad Request`	A aplicação não tem Account SID e Auth token próprios da Twilio (`FailedPrecondition`).
`401 Unauthorized`	A Twilio rejeitou as credenciais da aplicação (`Unauthenticated`).
`503 Service Unavailable`	A Twilio Content API retornou outro erro (`Unavailable`).

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.
expires_in (duração, por exemplo, "604800s"): por quanto tempo a entrada permanece na caixa de entrada, contado a partir da data de envio (o send_date agendado ou o momento da solicitação, para envios imediatos). Deve ser positivo. Ignorado quando expiration_date está definido.

Para definir um tempo de vida relativo em vez de uma data fixa, envie apenas expires_in:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

Se a sua conta tiver um tempo de vida máximo na caixa de entrada, um expiration_date ou expires_in que o ultrapasse é rejeitado.

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

Inteiros grandes em dados personalizados

LocalizedContent

Seleção de localidade para um dispositivo

Botões

Campos de push comuns

iOS (ios)

Android (android, huawei_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

Viber (viber)