# Referencia de Payload

Referencia para el mensaje `Payload` utilizado por [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/) al enviar a través de cualquier canal que no sea correo electrónico (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp).

<Aside type="note">
Para correo electrónico, consulte la [referencia del payload de correo electrónico](/es/developer/api-reference/messaging-api-v2/email-payload-reference/).
</Aside>

## Payload

- `preset` (string): código de [preajuste de push](/es/product/content/push-presets/) (formato `XXXXX-XXXXX`) para aplicar a este mensaje.
- `sms_preset` (string): código (formato `XXXXX-XXXXX`) de un [preajuste de SMS](/es/product/content/sms-presets/) guardado. Su texto por configuración regional se resuelve en el [`sms.body`](#sms-sms) 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`](#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`](#openaction)): acción que se activa cuando el usuario abre la notificación.
- `open_actions` (map&lt;Platform, `OpenAction`&gt;): 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.

```json
{
  "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

Mapea el código de configuración regional → contenido por plataforma. Las claves son códigos de dos letras [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) (por ejemplo, `"en"`, `"es"`) más la clave especial `"default"` para una traducción general. Las excepciones a ISO 639-1 son `"zh-Hant"` y `"zh-Hans"` para chino tradicional y simplificado.

```json
{
  "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 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 |
| `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 |
| `viber` | Mensaje de Viber |
| `whatsapp` | Mensaje de WhatsApp |
| `sms` | Mensaje SMS |

## 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` (duración, 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): habilitar o suprimir el sonido.
- `badges` (string): recuento de insignias (iOS) o análogo.
- `root_params` (object): anulaciones de payload sin procesar específicas de la plataforma.
- `inbox` ([`Inbox`](#inbox)): entrada de [Bandeja de entrada de mensajes](/es/developer/guides/message-inbox/mobile-message-inbox/).

```json
{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "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): 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.

```json
{
  "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): icono pequeño de la notificación.
- `banner` (string): URL de la 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`](#notificationpriority-enum)): 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.

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

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

```json
{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}
```

## Amazon (`amazon`)

Utiliza los campos comunes de push más `custom_icon` y `priority` ([`NotificationPriority`](#notificationpriority-enum)).

```json
{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "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 de string): argumentos de URL de Safari sustituidos en la plantilla de URL de Web Push.

```json
{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "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` (duración): temporizador de cierre automático.
- `button_text1` / `button_url1`, `button_text2` / `button_url2`: hasta dos botones de acción.

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

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

```json
{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}
```

## Windows (`windows`)

Windows utiliza una forma diferente:

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

```json
{
  "telegram": {
    "body": "Hello from 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.

```json
{
  "kakao": {
    "content": "Hello from 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 (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`.

```json
{
  "line": {
    "content": "Hello from 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 no se establece `template_id`.
- `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 se establece `template_id`.
- `template_params` (map&lt;string, string&gt;): 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 a los destinatarios de Viber como hwids en la forma `viber:<phone>` (E.164), por ejemplo `viber:+1234567890`.

Texto sin formato:

```json
{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}
```

Plantilla transaccional:

```json
{
  "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 el 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 las 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`.

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

## SMS (`sms`)

SMS tiene su propio bloque de plataforma dentro del [`Content`](#localizedcontent) 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`](#payload) a nivel de payload en el código (formato `XXXXX-XXXXX`) de un [preajuste de SMS](/es/product/content/sms-presets/) 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 aún así ajustar idiomas individuales.

```json
{
  "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 la acción realizada cuando el usuario abre el mensaje.

Exactamente uno de:

- `rich_media` ([`RichMedia`](#richmedia)): abrir una página de [Rich Media](/es/product/content/in-apps/).
- `deep_link`: abrir un deep link: `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)): abrir una URL.

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

La URL del deeplink y los valores de `params` admiten la sintaxis de [personalización Liquid](/es/developer/guides/personalization/liquid-templates/) — las expresiones se resuelven antes de que se abra el deep link.

### RichMedia


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

### Link


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

`shortener` es `NONE` (predeterminado) o `BITLY`.

## Inbox

Configura cómo aparece el mensaje en la Bandeja de entrada de mensajes.

```json
{
  "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 de la bandeja de entrada.
- `expiration_date` (timestamp): cuándo se elimina la entrada de la bandeja de entrada.

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

<Aside type="caution">
Envíe siempre la prioridad como uno de los valores de cadena anteriores. La API también acepta los equivalentes numéricos del enum (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 prioridad 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 de prioridad en lugar de devolver un error.
</Aside>

## Ejemplo: Enviar un push a un segmento

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

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