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).
control_group	string	Código o nombre del grupo de exclusión propio del envío que se aplicará a este mensaje. No restringe qué grupos de control se aplican: todos los grupos de control habilitados de la aplicación excluyen usuarios de los envíos de marketing, tanto si se establece este campo como si no. Mutuamente excluyente con holdout_percentage.
holdout_percentage	uint32	Extrae esta proporción del segmento, de 1 a 20, a un grupo de control limitado a este envío, además de los grupos de control habilitados de la aplicación, para medir el impacto de una sola campaña sin consumir los grupos compartidos. 0 (predeterminado) lo desactiva. Mutuamente excluyente con control_group.

Importante

Pushwoosh nombra el grupo de exclusión __holdout_<campaign code> (o __holdout_<message code> para un envío sin campaign) y reutiliza ese mismo grupo, con su porcentaje original, en cada envío posterior que comparta el código. La selección se fija la primera vez que se crea. Este grupo nunca aparece en Configuración > Grupos de control, y cambiar su tamaño, redistribuirlo, deshabilitarlo o eliminarlo devuelve FailedPrecondition, porque modificarlo en mitad de la medición invalidaría la comparación.

Los dispositivos seleccionados para el grupo de exclusión quedan excluidos de la entrega del mismo modo que con los grupos de control de la aplicación. No se les envía el mensaje, y el registro de seguimiento anota el descarte como Device is in control group. Un message_type de MESSAGE_TYPE_TRANSACTIONAL omite esta exclusión por completo, igual que con los grupos de control de la aplicación.

Establecer holdout_percentage junto con control_group, o un holdout_percentage superior a 20, devuelve 400:

Invalid holdout_percentage

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

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, Pushwoosh sustituye la hora en que se recibió la solicitud. Con follow_user_timezone sin establecer o en false, esto significa que el mensaje se envía inmediatamente a todos. Consulte la advertencia a continuación para follow_user_timezone: true. Máximo 30 días en el futuro.
after	duration	Alternativa a at. Enviar después de este desfase desde “ahora” (p. ej., "3600s"). Máximo 30 días.
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 o best_time_to_send está establecido.
best_time_to_send	timestamp	Opcional. Solo para envíos a segmentos. Cada dispositivo recibe el mensaje a su propia mejor hora dentro de las 24 horas siguientes a este momento. Los dispositivos sin mejor hora lo reciben en la fecha y hora de at / after en su zona horaria local. Consulte Mejor momento de envío.

Una hora de envío en el pasado no es instantánea para todos con follow_user_timezone

Con follow_user_timezone: true, el «ahora» sustituido se divide en franjas de hora local por dispositivo, en lugar de entregarse a todos los dispositivos a la vez. Las zonas horarias por detrás de UTC aún no han llegado a ese momento en su hora local, por lo que reciben el mensaje hasta 12 horas después. Las zonas horarias por delante de UTC ya han pasado ese momento en su hora local, por lo que siguen past_timezones_behaviour: enviado ahora, omitido (DO_NOT_SEND) o aplazado un día (NEXT_DAY) a esa misma hora local. La misma división se aplica al envío alternativo de best_time_to_send.

Mejor momento de envío

best_time_to_send es el equivalente en la API de la opción Mejor momento del Control Panel. at / after define el envío alternativo para los dispositivos sin datos suficientes para calcular una mejor hora. Pushwoosh toma la fecha y hora UTC de at / after y entrega el envío alternativo en esa fecha y hora en la zona horaria local de cada dispositivo, como con follow_user_timezone: true. Esto se aplica de forma implícita: deje follow_user_timezone sin establecer, ya que true se rechaza con BestTimeToSendWithUserTimezone. En el ejemplo siguiente, los dispositivos sin mejor hora reciben el mensaje a las 18:00 hora local del 1 de mayo. Donde esa hora local ya haya pasado cuando comienza el envío, se aplica past_timezones_behaviour.

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

Pushwoosh rechaza la solicitud con 400 a menos que se cumplan todas estas condiciones:

• La solicitud usa el tipo segment. Los envíos transactional no admiten best_time_to_send.
• follow_user_timezone no está establecido o es false.
• La hora de envío de at / after está en el futuro. Un at en el pasado, after: "0s" o un after omitido cuentan como «enviar ahora» y se rechazan.
• best_time_to_send no es anterior a la próxima hora en punto ni está a más de 30 días en el futuro. Se redondea hacia abajo a la hora en punto.
• La hora de envío de at / after no es posterior a best_time_to_send más 24 horas.

El reason del error (en el detalle ErrorInfo) indica la comprobación que falló:

reason	Causa
BestTimeToSendWithUserTimezone	follow_user_timezone es true.
BestTimeToSendTooEarly	best_time_to_send es anterior a la próxima hora en punto.
BestTimeToSendTooFarInFuture	best_time_to_send está a más de 30 días en el futuro.
SendDateAfterBestTimeToSend	at / after es posterior a best_time_to_send más 24 horas.
BestTimeToSendNotAllowed	best_time_to_send está establecido en un envío transactional.
BestTimeToSendWithSendNow	at / after se resuelve como «ahora» (at en el pasado o after igual a cero).

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