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.
silent_hours	SilentHours	Opcional. Envía el mensaje sin las horas de silencio de la aplicación.
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).
geo_zone	GeoZone	Opcional. Limita la audiencia a los dispositivos cuya última ubicación registrada se encuentra dentro de un círculo que usted define en esta solicitud. Se combina con code, expression o filter_expression mediante AND: un dispositivo debe coincidir con el segmento y estar dentro del círculo. Los dispositivos sin ubicación registrada se omiten. No disponible en NotifyTransactional.
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.
registration_type	RegistrationType	Qué hacer con los hwids que aún no están registrados en Pushwoosh. El valor predeterminado es REGISTRATION_TYPE_DEFAULT, que los omite. Establezca REGISTRATION_TYPE_FORCE para registrar nuevas direcciones de correo electrónico o números de teléfono y enviarles el mensaje en la misma solicitud.
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, silent_hours, 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.

Enviar a nuevas direcciones de correo electrónico y números de teléfono

Para email, SMS, WhatsApp, LINE, Viber y Kakao, el hwid es el propio destino, como la dirección de correo electrónico o el número de teléfono. Para enviar a un hwid que aún no está registrado, inclúyalo en hwids y establezca registration_type en REGISTRATION_TYPE_FORCE. Pushwoosh lo registra y entrega el mensaje en la misma solicitud, por lo que no necesita hacer antes una llamada a /registerDevice o /registerEmail.

registration_type solo funciona con hwids. Con users, un ID de usuario desconocido no se crea, sea cual sea el valor de registration_type.

Escriba cada hwid en el mismo formato en que /registerDevice lo almacena para ese canal:

Canal	Formato del hwid	Ejemplo
Email	Dirección de correo electrónico	new.customer@example.com
SMS	Número de teléfono en formato internacional	+14155552671
WhatsApp	Número de teléfono con el prefijo whatsapp:	whatsapp:+14155552671
Kakao	Número de teléfono con el prefijo kakao:	kakao:+821012345678
Viber	Número de teléfono con el prefijo viber:. Pushwoosh añade el prefijo si falta	viber:+14155552671
LINE	ID de usuario de LINE	U4af4980629a1b2c3d4e5f6a7b8c9d0e1

Mantenga los prefijos whatsapp: y kakao:. Sin ellos, el número se interpreta como un hwid de SMS. Si ese número ya está registrado para SMS, el envío encuentra el hwid de SMS, que no coincide con la plataforma de destino, y el destinatario se omite.

Pushwoosh comprueba los números de teléfono solo con return_unknown_identifiers: true. En ese caso, un hwid de SMS, WhatsApp o Kakao que no sea un número de teléfono válido no se registra y se devuelve en unknown_identifiers. Sin ese indicador, el valor se registra tal cual.

REGISTRATION_TYPE_FORCE no registra hwids en plataformas push, Telegram ni Facebook Messenger, ya que estas necesitan un token del SDK o del servicio de mensajería. Un hwid desconocido en estas plataformas se descarta sin aviso. No se devuelve en unknown_identifiers y no se le envía nada.

Para WhatsApp, registrar un número no abre la ventana de atención al cliente de 24 horas. Un número que no le ha escrito solo puede recibir una plantilla aprobada previamente indicada en whatsapp.content_id, no whatsapp.content de formato libre.

Ejemplo: Enviar a una nueva dirección de correo electrónico

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": ["EMAIL"],
      "hwids": { "list": ["new.customer@example.com"] },
      "registration_type": "REGISTRATION_TYPE_FORCE",
      "email_payload": {
        "subject": { "en": "Welcome aboard" },
        "body": "<p>Thanks for signing up!</p>"
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

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 en un envío transactional con return_unknown_identifiers: true o con segmentación por push_tokens. Los identificadores registrados mediante REGISTRATION_TYPE_FORCE no se incluyen.

/getMessageDetails no encuentra un mensaje transactional enviado de inmediato a menos de 10 usuarios y menos de 10 dispositivos, porque ese mensaje no se almacena. Consulte Mensajes enviados de inmediato a menos de 10 destinatarios.

No se encontraron destinatarios

Con return_unknown_identifiers: true o segmentación por push_tokens, Pushwoosh busca cada destinatario antes de crear el mensaje. Si ninguno está registrado, Notify devuelve HTTP 400 con este error y no se crea ningún mensaje:

{
  "code": 9,
  "message": "No recipients found",
  "details": [ ... ]
}

Si se encuentra al menos un destinatario, la solicitud se completa correctamente y el resto se incluye en unknown_identifiers. Para enviar en su lugar a nuevas direcciones de correo electrónico o números de teléfono, establezca registration_type en REGISTRATION_TYPE_FORCE.

Para email, las direcciones no válidas y las que rebotaron anteriormente se eliminan antes de esta comprobación, sin incluirse en unknown_identifiers. Si después de eso no queda ninguna dirección, Notify devuelve 200 con un message_code, pero no se crea ningún mensaje y no se envía nada.

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). Máximo 30 días en el futuro. Con follow_user_timezone sin establecer o en false, un at en el pasado se sustituye por la hora en que se recibió la solicitud, por lo que el mensaje se envía inmediatamente a todos. Con follow_user_timezone: true, un at en el pasado se mantiene tal cual. Consulte la advertencia a continuación.
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, un at en el pasado no se traslada a «ahora». Su fecha y hora UTC se siguen dividiendo en franjas de hora local por dispositivo. Las zonas horarias en las que esa hora local aún no ha llegado reciben el mensaje a esa hora. Las zonas horarias en las que ya ha pasado 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).

GeoZone

Un círculo puntual para geo_zone, definido en la propia solicitud. No es una geozona guardada: no intervienen las campañas geográficas ni la API de Geozonas, y no se almacena nada en la aplicación.

{ "lat": 40.7128, "lng": -74.006, "range": 500 }

Campo	Tipo	Descripción
lat	double	Latitud del centro del círculo, en grados. Obligatorio.
lng	double	Longitud del centro del círculo, en grados. Obligatorio.
range	double	Radio del círculo en metros. Obligatorio.

Precaución

La API no valida estos valores. Un campo omitido se interpreta como 0, y un lat / lng fuera de rango o un range de 0 no se rechaza. Un envío así se acepta con un código de mensaje, pero alcanza pocos dispositivos o ninguno, en lugar de devolver 400.

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".

SilentHours

{ "avoid": true }

Los mensajes de marketing respetan las horas de silencio de la aplicación de forma predeterminada: durante el período de silencio, se retienen hasta que termina o no se envían, según la configuración del canal. Establezca avoid en true para enviar este mensaje incluso durante el período de silencio. Los mensajes con message_type MESSAGE_TYPE_TRANSACTIONAL nunca se retienen por las horas de silencio, por lo que no necesitan este campo.

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 RegistrationType

• REGISTRATION_TYPE_DEFAULT: omite los identificadores que no están registrados en Pushwoosh. Predeterminado.
• REGISTRATION_TYPE_NONE: envía a cada hwid de la lista sin guardar un dispositivo para él.
• REGISTRATION_TYPE_FORCE: registra cada hwid desconocido como dispositivo en el canal de destino y luego le envía el mensaje. Se aplica a email, SMS, WhatsApp, LINE, Viber y Kakao.

Enumeración de MessageType

• MESSAGE_TYPE_UNSPECIFIED: equivalente a MESSAGE_TYPE_MARKETING.
• MESSAGE_TYPE_MARKETING: sujeto al filtrado del grupo de control, al límite de frecuencia y a las horas de silencio.
• MESSAGE_TYPE_TRANSACTIONAL: omite el filtrado del grupo de control, el límite de frecuencia y las horas de silencio. Ú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