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

Nota

Para correo electrónico, consulte la referencia de payload de correo electrónico.

Payload

• preset (string): código del preajuste de push (formato XXXXX-XXXXX) para aplicar a este mensaje.
• sms_preset (string): código (formato XXXXX-XXXXX) de un preajuste de SMS guardado. Su texto por configuración regional se resuelve en el sms.body de cada configuración regional. Un sms.body en línea para una configuración regional dada anula el preajuste para esa configuración regional. El preajuste debe pertenecer a la misma aplicación que el mensaje.
• content (LocalizedContent): contenido del mensaje. Mutuamente excluyente con silent.
• silent (bool): envía 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 de la enumeración Platform.
• voip_push (bool): notificación VoIP de iOS.

{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hola", "body": "Toca para ver" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}

LocalizedContent

Mapea el código de configuración regional → 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 la configuración regional para un dispositivo

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

1. Coincidencia exacta con el idioma del dispositivo.
2. Clave "default".
3. Clave "en".
4. Cualquier otra configuración regional 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 configuración regional, envíe solo "default".

Cada entrada de configuración regional es un objeto Content con bloques opcionales por plataforma. Solo complete 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
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
viber	Mensaje de Viber
whatsapp	Mensaje de WhatsApp
sms	Mensaje SMS

Campos push comunes

Estos campos son compartidos por los bloques ios, android, huawei_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 el servidor de push debe retener la notificación para un dispositivo sin conexión.
• sound (string): nombre del archivo de sonido.
• sound_enabled (bool): activa o suprime el sonido.
• badges (string): recuento de notificaciones (iOS) o análogo.
• root_params (object): anulaciones de payload sin procesar específicas de la plataforma.
• inbox (Inbox): entrada en Message Inbox.

{
  "android": {
    "title": "Hola",
    "body": "Toca para ver",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}

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): recorta el contenido para que quepa.
• 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.

{
  "ios": {
    "title": "Hola",
    "body": "Toca para ver",
    "subtitle": "Nueva actualización",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}

Android (android, huawei_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 de entrada.
• 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.

{
  "android": {
    "title": "Hola",
    "body": "Toca para ver",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}

macOS (mac_os)

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

{
  "mac_os": {
    "title": "Hola",
    "body": "Toca para ver",
    "subtitle": "Nueva actualización",
    "action": "https://example.com/promo"
  }
}

Amazon (amazon)

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

{
  "amazon": {
    "title": "Hola",
    "body": "Toca para ver",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}

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.

{
  "safari": {
    "title": "Hola",
    "body": "Toca para ver",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}

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.

{
  "chrome": {
    "title": "Hola",
    "body": "Toca para ver",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Abrir",
    "button_url1": "https://example.com/promo"
  }
}

Firefox (firefox)

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

{
  "firefox": {
    "title": "Hola",
    "body": "Toca para ver",
    "icon": "https://cdn.example.com/icon.png"
  }
}

Windows (windows)

Windows utiliza una forma diferente:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hola", "body": "Toca para ver" },
    "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.

{
  "telegram": {
    "body": "Hola desde Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}

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.

{
  "kakao": {
    "content": "Hola desde Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}

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 (utilizada 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.

{
  "line": {
    "content": "Hola desde Pushwoosh",
    "template": "promo_carousel"
  }
}

Viber (viber)

Un mensaje de Viber es un cuerpo de texto libre o una plantilla transaccional preaprobada (Omni Messaging / MStat) a la que se hace referencia por id e idioma.

• body (string): mensaje de texto sin formato. Requerido cuando template_id no está establecido.
• template_id (string): id de una plantilla transaccional preaprobada. Cuando se establece, tiene prioridad sobre body.
• template_lang (string): configuración regional de la plantilla. Requerido cuando template_id está establecido.
• template_params (map<string, string>): enlaces de clave/valor sustituidos en la plantilla, p. ej. { "name": "John", "code": "123456" }.
• all_devices (bool): false (predeterminado) entrega solo al dispositivo principal del usuario; true entrega a todos los dispositivos del usuario.

Se debe establecer al menos uno de body o template_id. Cuando se establece template_id, se requiere template_lang.

Dirija los destinatarios de Viber como hwids en el formato viber:<teléfono> (E.164), por ejemplo viber:+1234567890.

Texto sin formato:

{
  "viber": {
    "body": "Hola desde Pushwoosh"
  }
}

Plantilla transaccional:

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

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): configuración regional de la plantilla que debe coincidir exactamente con la configuración regional 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 configuración regional 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.

{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}

SMS (sms)

SMS tiene su propio bloque de plataforma dentro del Content de cada configuración regional, junto con ios, android y los otros canales de mensajería.

• body (string): texto del SMS para la configuración regional. Requerido cuando el bloque sms está presente.

Hay dos formas de proporcionar el texto:

• En línea — establezca sms.body por configuración regional en localized_content.
• Desde un preajuste — establezca el sms_preset a nivel de payload en el código (formato XXXXX-XXXXX) de un preajuste de SMS guardado. Su contenido por configuración regional se resuelve en sms.body para cada configuración regional que define el preajuste. Un sms.body en línea para una configuración regional anula el preajuste para esa configuración regional, por lo que puede reutilizar un preajuste y aun así ajustar idiomas individuales.

{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Tu pedido ha sido enviado." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}

MMS

Agregar subject y file_urls a un bloque sms convierte el mensaje en un MMS. Solo AbleMobile tiene un punto final de MMS; otros proveedores de SMS ignoran ambos campos y entregan solo el body de texto sin formato.

• subject (string): asunto del MMS. Requiere al menos una entrada en file_urls; un asunto sin archivos adjuntos es rechazado. Hasta 40 caracteres ASCII, o 13 caracteres si el asunto contiene caracteres no ASCII.
• file_urls (array of string): hasta 3 URL de archivos adjuntos. Cada una debe ser una URL https absoluta que termine en .jpg o .gif; .jpeg y .png son rechazados por la validación, incluso para un archivo JPEG o PNG genuino, porque el proveedor no puede decodificarlos. Cada archivo también debe ser de 200 KB o más pequeño; AbleMobile rechaza todo el envío si algún archivo adjunto es más pesado.
• message_at (int): índice en file_urls (base 0) después del cual se muestra el texto del cuerpo del SMS.

subject y file_urls admiten la personalización con Liquid, al igual que body.

{
  "sms": {
    "body": "Tu pedido ha sido enviado.",
    "subject": "Actualización del pedido",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

OpenAction

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

Exactamente uno de:

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

{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}

La URL del deep link y los valores de params admiten la sintaxis de personalización con Liquid; las expresiones se resuelven antes de que se abra el deep link.

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.

Enumeración 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

Precaución

Envíe siempre priority como uno de los valores de cadena anteriores. La API también acepta los equivalentes numéricos de la enumeración (1-5, que coinciden con el orden anterior), pero ese mapeo es un detalle interno de protobuf, no un contrato compatible; no confíe en él.

Un valor de priority no reconocido (una cadena mal escrita o un número fuera de rango) no se rechaza: la API lo descarta silenciosamente y la notificación se envía sin ningún campo priority en lugar de devolver un error.

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": "Tu pedido", "body": "El pedido #42 ha sido enviado." },
              "android": { "title": "Tu pedido", "body": "El pedido #42 ha sido enviado." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'