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 los dos tipos:

• segment: dirige a un segmento de audiencia por código de segmento, o —sin crear un segmento primero— 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.

Forma

{
  "segment": { ... },      // O
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

Campo	Tipo	Descripción
transaction_id	string	Opcional. Clave de idempotencia para la solicitud — funciona tanto con segment como con transactional. Una llamada repetida con el mismo transaction_id en un plazo de 5 minutos devuelve el message_code original en lugar de enviar un mensaje duplicado. Utiliza un UUID u otro valor único por envío lógico.

Consejo

Pasa un encabezado X-Request-ID para correlacionar el mensaje creado con tu solicitud para un seguimiento de extremo a extremo — consulta ID de solicitud.

Solo se verifica la clave, no el payload

La deduplicación se basa únicamente en transaction_id. Si un reintento reutiliza el mismo transaction_id pero envía un cuerpo segment / transactional diferente, se devuelve el message_code original y el nuevo cuerpo se descarta silenciosamente — no se compara con la primera solicitud. Nunca reutilices un transaction_id en mensajes lógicamente diferentes.

Consejo

Este es el mismo mecanismo de deduplicación que transactionId en la API de Mensajes heredada, compartiendo la misma ventana de almacenamiento de 5 minutos, por lo que una solicitud reintentada se deduplica tanto en /createMessage como en Notify. No está relacionado con el atributo transaction_id en los eventos de ingresos PW_Conversion, que Pushwoosh almacena tal cual y no utiliza para la deduplicación.

NotifySegment

Se dirige a los usuarios que coinciden con un segmento de audiencia o una expresión de filtro. Establece exactamente uno de code, expression o filter_expression. Para expression y filter_expression, no es necesario crear un segmento de antemano — la expresión se evalúa en línea solo para este envío.

Elegir entre código y expresiones en línea

Solo un segmento guardado referenciado por code puede usar la precompilación de entrega de alta velocidad. expression y filter_expression se evalúan en el momento del envío y nunca se precompilan.

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 de un segmento guardado previamente. Mutuamente excluyente con expression y filter_expression.
expression	string	Expresión Seglang, evaluada solo para este envío — no se requiere un segmento guardado. Mutuamente excluyente con code y filter_expression.
filter_expression	FilterExpression	La misma lógica que expression, como un objeto estructurado en lugar de una cadena seglang. Mutuamente excluyente con code y expression. El esquema de FilterExpression no está documentado públicamente — solicítalo al soporte de Pushwoosh si necesitas la forma estructurada.
payload	Payload	Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. 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.
campaign_name	string	Nombre interno de este mensaje, se muestra como el título de la fila en Message History y en su exportación. No tiene relación con campaign arriba. No agrupa mensajes ni afecta la entrega. Máximo 255 caracteres, recortado. Omítelo o déjalo vacío para que el título de la fila se tome del propio contenido del payload.
frequency_capping	FrequencyCapping	Límites de frecuencia por usuario.
send_rate	SendRate	Limitación de 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 las analíticas posteriores.
use_latest_user_device	bool	Cuando es true, entrega el mensaje al dispositivo más recientemente activo de cada usuario (el que tiene la última apertura de la aplicación más reciente) en lugar de a cada dispositivo que coincida con el segmento. Limitado a platforms: solo se consideran los dispositivos en esas plataformas, y si ninguno tiene datos de última apertura de la aplicación, se utiliza el primer dispositivo coincidente en lugar de descartar el envío. El valor predeterminado es false (enviar a cada dispositivo).

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, enviar 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 / LINE / WhatsApp / Viber / Facebook Messenger.
email_payload	EmailPayload	Payload de correo electrónico.
return_unknown_identifiers	bool	Cuando es true, la lista unknown_identifiers de la respuesta contiene los identificadores que no se encontraron.
use_latest_user_device	bool	Solo se aplica cuando se dirige a users. Mismo comportamiento que en NotifySegment anterior — entrega un mensaje por usuario en lugar de uno por dispositivo, limitado a platforms. El valor predeterminado es false.
campaign, campaign_name, 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,
      "use_latest_user_device": 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 completa solo cuando se estableció 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 está 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. Para deshabilitar el límite, omite frequency_capping por completo, o envía days: 0 junto con count: 0.

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

• days (int, 1–30, o 0 para deshabilitar el límite): ventana de retrospectiva. Debe enviarse junto con count — si uno es 0, el otro también debe ser 0; enviar uno como 0 mientras el otro no es cero devuelve 400.
• count (int, 1 o superior, o 0 para deshabilitar el límite): número máximo de mensajes permitidos dentro de days. Misma regla de emparejamiento que days.
• exclude (bool): excluye estrictamente a los usuarios que ya han alcanzado el límite.
• avoid (bool): evita suavemente a los usuarios que ya han alcanzado el límite (aún cuentan para las analíticas).

Importante

Enviar days y count con valores cero no coincidentes (p. ej., {"days": 0, "count": 5}) devuelve 400. Esta validación es un cambio disruptivo en Notify — los clientes que anteriormente dependían de que un 0 solitario se ignorara silenciosamente ahora recibirán un error.

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 Plataforma

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

Enumeración de MessageType

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

Relacionado

Notificar en lote

Cancelar

Referencia de payload

Referencia de payload de correo electrónico

Migración desde v1