# 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`](#notifysegment): se dirige a un segmento de audiencia por código de segmento, una expresión [seglang](/es/developer/api-reference/segmentation-filters-api/segmentation-language/) o una expresión de filtro estructurada.
- [`transactional`](#notifytransactional): se envía a una lista explícita de hwids, ID de usuario, push tokens o dispositivos de prueba.
```json title="Forma"
{
"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`](#schedule) | Cuándo y cómo enviar. Requerido. |
| `application` | string | [Código de aplicación](/es/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array de [`Platform`](#platform-enum) | Plataformas a las que se dirige el mensaje. |
| `code` | string | [Código de segmento](/es/developer/api-reference/api-identifiers/#segment--filter-code). Mutuamente excluyente con `expression` y `filter_expression`. |
| `expression` | string | Expresión [Seglang](/es/developer/api-reference/segmentation-filters-api/segmentation-language/). |
| `filter_expression` | `FilterExpression` | Expresión de filtro estructurada (avanzado). |
| `payload` | [`Payload`](/es/developer/api-reference/messaging-api-v2/payload-reference/) | Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Mutuamente excluyente con `email_payload`. |
| `email_payload` | [`EmailPayload`](/es/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload de email. |
| `campaign` | string | [Código de campaña](/es/developer/api-reference/api-identifiers/#campaign-code) al que atribuir este mensaje. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Límites de frecuencia por usuario. |
| `send_rate` | [`SendRate`](#sendrate) | Limitación de velocidad para el envío. |
| `message_type` | [`MessageType`](#messagetype-enum) | `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 los análisis posteriores. |
### Ejemplo: Enviar 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": { "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`](#schedule) | Requerido. |
| `application` | string | [Código de aplicación](/es/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array de [`Platform`](#platform-enum) | 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](/es/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid). |
| `users` | `{ "list": [string, ...] }` | Enviar solo a estos [ID de usuario](/es/developer/pushwoosh-knowledge-hub/users-userids/). |
| `push_tokens` | `{ "list": [string, ...] }` | Enviar solo a estos [push tokens](/es/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token). |
| `payload` | [`Payload`](/es/developer/api-reference/messaging-api-v2/payload-reference/) | Payload de Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. |
| `email_payload` | [`EmailPayload`](/es/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload de email. |
| `return_unknown_identifiers` | bool | Cuando es `true`, la respuesta `unknown_identifiers` enumera los identificadores que no se encontraron. |
| `use_latest_user_device` | bool | Solo se aplica cuando se dirige a `users`. Cuando es `true`, el mensaje se entrega al dispositivo activo más reciente de cada usuario (el que tiene la última apertura de aplicación más reciente) en lugar de a todos los dispositivos vinculados a ese ID de usuario. El valor predeterminado es `false` (enviar a todos los dispositivos). |
| `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
```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": ["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
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| Campo | Tipo | Descripción |
|---|---|---|
| `message_code` | string | [Código de mensaje](/es/developer/api-reference/api-identifiers/#message-code) único. Úselo con los endpoints [`/getMessageDetails`](/es/developer/api-reference/messages-api/#getmessagedetails) y 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
```json
{
"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. Para deshabilitar la limitación, omita `frequency_capping` por completo o envíe `days: 0` junto con `count: 0`.
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, o `0` para deshabilitar la limitación): ventana de retrospectiva. Debe enviarse junto con `count`; si uno es `0`, el otro también debe ser `0`; enviar uno como `0` mientras que el otro no es cero devuelve `400`.
- `count` (int, 1 o superior, o `0` para deshabilitar la limitación): número máximo de mensajes permitidos dentro de `days`. Misma regla de emparejamiento que `days` arriba.
- `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
```json
{ "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 Platform
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.
### Enumeración MessageType
- `MESSAGE_TYPE_UNSPECIFIED`: equivalente a `MESSAGE_TYPE_MARKETING`.
- `MESSAGE_TYPE_MARKETING`: sujeto al filtrado del grupo de control y a la limitación de frecuencia.
- `MESSAGE_TYPE_TRANSACTIONAL`: omite el filtrado del grupo de control y la limitación de frecuencia. Úselo para confirmaciones de pedidos, OTP y flujos críticos similares.
## Relacionado