Referencia de Payload

Referencia para el mensaje Payload utilizado por Notify al enviar a través de cualquier canal que no sea correo electrónico (push, SMS, Telegram, Kakao, LINE, WhatsApp).

Payload

preset (string): código de preset para aplicar a este mensaje.
content (LocalizedContent): contenido del mensaje. Mutuamente excluyente con silent.
silent (bool): enviar un push silencioso (solo datos). Mutuamente excluyente con content.
custom_data (object): JSON de formato libre reenviado al SDK del cliente como el parámetro u.
open_action (OpenAction): acción que se activa cuando el usuario abre la notificación.
open_actions (map<Platform, OpenAction>): anulación por plataforma de open_action. La clave es un valor numérico del enum Platform.
voip_push (bool): notificación VoIP de iOS.

LocalizedContent

Mapea el código de localización → contenido por plataforma. Las claves son códigos de dos letras ISO 639-1 (por ejemplo, "en", "es") más la clave especial "default" para una traducción genérica. Las excepciones a ISO 639-1 son "zh-Hant" y "zh-Hans" para chino tradicional y 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" }
    }
  }
}

Selección de localización para un dispositivo

El contenido entregado a un dispositivo se elige en este orden:

Coincidencia exacta con el idioma del dispositivo.
Clave "default".
Clave "en".
Cualquier otra localización presente en el mapa.

Proporcione al menos uno de "default" o "en" para que cada dispositivo tenga una alternativa determinista. Si no espera variantes por localización, envíe solo "default".

Cada entrada de localización es un objeto Content con bloques opcionales por plataforma. Rellene solo las plataformas a las que se dirige.

Bloque de plataforma	Canal
`ios`	Push de iOS
`android`	Push de Android (FCM)
`huawei_android`	Push de Huawei Android
`baidu_android`	Push de Baidu Android
`mac_os`	Push de macOS
`amazon`	Push de Amazon (ADM)
`safari`	Push web de Safari
`chrome`	Push web de Chrome
`firefox`	Push web de Firefox
`ie`	Push web de Internet Explorer
`windows`	Push de Windows (tile / toast / badge)
`telegram`	Mensaje de Telegram
`kakao`	Mensaje de Kakao
`line`	Mensaje de LINE
`whatsapp`	Mensaje de WhatsApp

Campos comunes de push

Estos campos son compartidos por los bloques ios, android, huawei_android, baidu_android, mac_os, amazon, safari, chrome y firefox (el soporte varía. Los campos no utilizados son ignorados por la plataforma correspondiente).

title (string): título de la notificación.
body (string): cuerpo de la notificación.
time_to_live (duration, p. ej. "3600s"): cuánto tiempo debe retener el servidor de push la notificación para un dispositivo sin conexión.
sound (string): nombre del archivo de sonido.
sound_enabled (bool): activar o suprimir el sonido.
badges (string): contador de insignia (iOS) o análogo.
root_params (object): anulaciones de payload sin procesar específicas de la plataforma.
inbox (Inbox): entrada de Message Inbox.

iOS (`ios`)

subtitle (string): subtítulo de la notificación de iOS.
is_critical (bool): alerta crítica (requiere autorización).
attachment (string): URL de un archivo adjunto multimedia.
thread_id (string): identificador de hilo para notificaciones agrupadas.
trim_content (bool): recortar el contenido para que se ajuste.
category_id (string): identificador UNNotificationCategory para acciones interactivas.
interruption_level (string): passive, active, time-sensitive o critical.
collapse_id (string): identificador de colapso de APNs. Las notificaciones con el mismo collapse_id se reemplazan entre sí en el dispositivo.

Android (`android`, `huawei_android`, `baidu_android`)

icon (string): icono pequeño de la notificación.
banner (string): URL de imagen grande.
delivery_priority (NORMAL | HIGH): prioridad de entrega de FCM.
vibration (bool): vibración al recibir.
led_color (string, hex): color del LED de notificación.
icon_background_color (string, hex): color de fondo del icono.
show_on_lockscreen (bool): mostrar en la pantalla de bloqueo.
custom_icon (string): URL de un icono personalizado.
priority (NotificationPriority): prioridad en la bandeja.
group_id (string): clave de grupo de notificación.
collapse_key (string): clave de colapso de FCM. Las notificaciones con la misma collapse_key se reemplazan entre sí mientras el dispositivo está sin conexión.

macOS (`mac_os`)

Utiliza los campos comunes de push más subtitle y action (URL que se abre cuando el usuario hace clic en la notificación).

Amazon (`amazon`)

Utiliza los campos comunes de push más custom_icon y priority (NotificationPriority).

Safari (`safari`)

action (string): URL que se abre cuando el usuario hace clic en la notificación.
url_arguments (array of string): argumentos de URL de Safari sustituidos en la plantilla de URL de Web Push.

Chrome (`chrome`)

icon, image (string): URL del icono pequeño y de la imagen grande.
duration (duration): temporizador de cierre automático.
button_text1 / button_url1, button_text2 / button_url2: hasta dos botones de acción.

Firefox (`firefox`)

Utiliza solo title, body, icon, root_params e inbox.

Windows (`windows`)

Windows utiliza una forma diferente:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}

type es TILE, TOAST o BADGE.
template (estructurado) o raw ({ "content": "<raw xml>" }) — exactamente uno.

Telegram (`telegram`)

body (string): texto del mensaje.
content_variables (string): variables en formato de cadena JSON para la plantilla del lado del bot.

Kakao (`kakao`)

content (string): contenido del mensaje.
template (string): código de plantilla aprobado.
content_variables (string): enlaces de variables de plantilla en formato de cadena JSON.

LINE (`line`)

content (string): cuerpo de texto sin formato.
template (string): código de una plantilla de LINE configurada en el Panel de Control de Pushwoosh (utilizado para enviar mensajes de imagen, carrusel o flexibles). Para contenido enriquecido, preconfigure la plantilla en el Panel de Control y haga referencia a ella aquí.

Se debe establecer al menos uno de content o template.

WhatsApp (`whatsapp`)

Los mensajes de WhatsApp pasan por Meta y están sujetos a las reglas de mensajería de Meta. La división clave es entre texto de formato libre (solo se entrega dentro de la ventana de servicio al cliente de 24 horas abierta por un mensaje entrante del usuario) y plantillas aprobadas (requeridas para la iniciación saliente y para cualquier mensaje fuera de la ventana de 24 horas).

content (string): texto del mensaje de formato libre. Entregado por Meta solo dentro de la ventana de 24 horas.
content_id (string): nombre de una plantilla de Meta preaprobada (p. ej. "hello_world"). Requerido para la iniciación saliente o cualquier mensaje fuera de la ventana de 24 horas.
language (string): localización de la plantilla que debe coincidir exactamente con la localización aprobada en Meta (p. ej. "en_US", "en_GB"). Solo tiene sentido junto con content_id. Esto es independiente de la clave externa LocalizedContent. La clave externa selecciona el contenido para un dispositivo, y language selecciona la localización de la plantilla de Meta para ese contenido.
content_variables (string): objeto JSON que mapea los marcadores de posición del cuerpo, p. ej. "{\"1\":\"John\"}".
button_url_variables (string): objeto JSON que mapea los marcadores de posición de la URL del botón con clave por índice de botón, p. ej. "{\"0\":\"https://...\"}".
header_variables (string): objeto JSON que mapea los marcadores de posición del encabezado con clave por tipo, p. ej. "{\"image\":\"https://...\"}".

Se debe establecer al menos uno de content o content_id.

SMS

SMS utiliza el flujo de mensajes genérico. El bloque de plataforma sms está reservado. Proporcione el texto a través del campo común body en cualquier bloque de plataforma rellenado. El ID del remitente y otras opciones del proveedor provienen de la configuración de SMS de la aplicación. Consulte Configuración de SMS.

OpenAction

Define la acción realizada cuando el usuario abre el mensaje.

Exactamente uno de:

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

RichMedia

{ "code": "XXXXX-XXXXX" }        // por código de Rich Media
{ "url":  "https://..." }        // por URL remota

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener es NONE (predeterminado) o BITLY.

Inbox

Configura cómo aparece el mensaje en Message Inbox.

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}

image_url (string): imagen que se muestra en la entrada del inbox.
expiration_date (timestamp): cuándo se elimina la entrada del inbox.

Enum NotificationPriority

Controla la prioridad de la notificación en el dispositivo de destino, desde PRIORITY_MIN (la más baja) hasta PRIORITY_MAX (la más alta).

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Ejemplo: Enviar un push a un 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"
    }
  }'

Ejemplo: Push transaccional por ID de usuario

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

Referencia de Payload

Payload

LocalizedContent

Selección de localización para un dispositivo

Campos comunes de push

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)

WhatsApp (whatsapp)

SMS