Notificar

POST https://api.pushwoosh.com/messaging/v2/notify

Crea y programa un único mensaje.

Estructura de la solicitud

El cuerpo de la solicitud es un NotifyRequest con exactamente uno de dos tipos:

segment: se dirige a un segmento de audiencia por código de segmento, una expresión seglang o una expresión de filtro estructurada.
transactional: envía a una lista explícita de hwids, ID de usuario, tokens push o dispositivos de prueba.

{
  "segment": { ... }       // O
  "transactional": { ... }
}

NotifySegment

Se dirige a los usuarios que coinciden con un segmento de audiencia o una expresión de filtro.

Campo	Tipo	Descripción
`schedule`	`Schedule`	Cuándo y cómo enviar. Requerido.
`application`	string	Código de aplicación.
`platforms`	array de `Platform`	Plataformas a las que se dirige el mensaje.
`code`	string	Código de segmento. Mutuamente excluyente con `expression` y `filter_expression`.
`expression`	string	Expresión Seglang.
`filter_expression`	`FilterExpression`	Expresión de filtro estructurada (avanzada).
`payload`	`Payload`	Payload de Push / SMS / Telegram / Kakao. Mutuamente excluyente con `email_payload`.
`email_payload`	`EmailPayload`	Payload de correo electrónico.
`campaign`	string	Código de campaña al que atribuir este mensaje.
`frequency_capping`	`FrequencyCapping`	Límites de frecuencia por usuario.
`send_rate`	`SendRate`	Limitación de la velocidad para el envío.
`message_type`	`MessageType`	`MESSAGE_TYPE_MARKETING` (predeterminado) o `MESSAGE_TYPE_TRANSACTIONAL`. Controla el filtrado del grupo de control.
`dynamic_content_placeholders`	map<string, string>	Reemplaza los marcadores de posición en el contenido.
`meta_data`	object	Metadatos de formato libre reenviados a análisis posteriores.

Ejemplo: Enviar 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":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

Envía a una lista explícita de destinatarios.

Campo	Tipo	Descripción
`schedule`	`Schedule`	Requerido.
`application`	string	Código de aplicación.
`platforms`	array de `Platform`	Plataformas a las que se dirige el mensaje.
`test_devices`	bool	Si es `true`, se envía solo a los dispositivos de prueba de la aplicación.
`hwids`	`{ "list": [string, ...] }`	Enviar solo a estos hwids.
`users`	`{ "list": [string, ...] }`	Enviar solo a estos ID de usuario.
`push_tokens`	`{ "list": [string, ...] }`	Enviar solo a estos tokens push.
`payload`	`Payload`	Payload de Push / SMS / Telegram / Kakao.
`email_payload`	`EmailPayload`	Payload de correo electrónico.
`return_unknown_identifiers`	bool	Cuando es `true`, el campo `unknown_identifiers` de la respuesta enumera los identificadores que no se encontraron.
`campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data`		Ver `NotifySegment` arriba.

test_devices, hwids, users y push_tokens son mutuamente excluyentes. Se debe establecer exactamente uno.

Ejemplo: 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": ["user-123", "user-456"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Your order has shipped." } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

Respuesta

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Campo	Tipo	Descripción
`message_code`	string	Código de mensaje único. Úsalo con `/getMessageDetails` y los endpoints de estadísticas de mensajes.
`unknown_identifiers`	array de string	Identificadores no encontrados en la cuenta. Se rellena solo cuando se establece `return_unknown_identifiers: true` en el tipo `transactional`.

Tipos compartidos

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

Campo	Tipo	Descripción
`at`	timestamp	Hora de envío absoluta (RFC 3339). Si es en el pasado, el mensaje se envía inmediatamente. Máximo 14 días en el futuro.
`after`	duration	Alternativa a `at`. Enviar después de este desfase desde “ahora” (p. ej., `"3600s"`).
`follow_user_timezone`	bool	Cuando es `true`, cada dispositivo recibe el mensaje a la hora `at` en su zona horaria local.
`past_timezones_behaviour`	enum	`PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (predeterminado), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND` o `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. Solo tiene sentido cuando `follow_user_timezone` es `true`.

FrequencyCapping

Límites de frecuencia por usuario para envíos de marketing.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

days (int, 1–30): ventana de retrospectiva.
count (int): número máximo de mensajes permitidos dentro de days.
exclude (bool): excluye de forma estricta a los usuarios que ya han alcanzado el límite.
avoid (bool): evita de forma flexible a los usuarios que ya han alcanzado el límite (todavía cuentan para los análisis).

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

Limita la velocidad del envío. value es el número de mensajes por bucket; un bucket típico es "1s".

Enumeración de Platform

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, BAIDU_ANDROID, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP.

Enumeración de MessageType

MESSAGE_TYPE_UNSPECIFIED: equivalente a MESSAGE_TYPE_MARKETING.
MESSAGE_TYPE_MARKETING: sujeto a filtrado de grupo de control y límite de frecuencia.
MESSAGE_TYPE_TRANSACTIONAL: omite el filtrado de grupo de control y el límite de frecuencia. Úsalo para confirmaciones de pedidos, OTP y flujos críticos similares.

Relacionado

Referencia de Payload

Referencia de payload de correo electrónico

Migración desde v1