# Notify
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
Создает и планирует отправку одного сообщения.
## Структура запроса
Тело запроса — это `NotifyRequest` одного из двух видов:
- [`segment`](#notifysegment): таргетирование на сегмент аудитории по коду сегмента, выражению [seglang](/ru/developer/api-reference/segmentation-filters-api/segmentation-language/) или структурированному выражению фильтра.
- [`transactional`](#notifytransactional): отправка по определенному списку hwids, User ID, push-токенов или тестовых устройств.
```json title="Shape"
{
"segment": { ... } // ИЛИ
"transactional": { ... }
}
```
## NotifySegment
Таргетируется на пользователей, которые соответствуют сегменту аудитории или выражению фильтра.
| Поле | Тип | Описание |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Когда и как отправлять. Обязательное поле. |
| `application` | string | [Код приложения](/ru/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | Платформы, на которые нацелено сообщение. |
| `code` | string | [Код сегмента](/ru/developer/api-reference/api-identifiers/#segment--filter-code). Взаимоисключающий с `expression` и `filter_expression`. |
| `expression` | string | Выражение [Seglang](/ru/developer/api-reference/segmentation-filters-api/segmentation-language/). |
| `filter_expression` | `FilterExpression` | Структурированное выражение фильтра (расширенное). |
| `payload` | [`Payload`](/ru/developer/api-reference/messaging-api-v2/payload-reference/) | Полезная нагрузка (payload) для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Взаимоисключающий с `email_payload`. |
| `email_payload` | [`EmailPayload`](/ru/developer/api-reference/messaging-api-v2/email-payload-reference/) | Полезная нагрузка (payload) для Email. |
| `campaign` | string | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code), к которой будет отнесено это сообщение. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Ограничения по частоте отправки для каждого пользователя. |
| `send_rate` | [`SendRate`](#sendrate) | Ограничение скорости отправки. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (по умолчанию) или `MESSAGE_TYPE_TRANSACTIONAL`. Управляет фильтрацией по контрольной группе. |
| `dynamic_content_placeholders` | map<string, string> | Заменяет плейсхолдеры в контенте. |
| `meta_data` | object | Метаданные в свободной форме, передаваемые в системы аналитики. |
### Пример: Отправка сегменту
```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
Отправляет сообщение определенному списку получателей.
| Поле | Тип | Описание |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Обязательное поле. |
| `application` | string | [Код приложения](/ru/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | Платформы, на которые нацелено сообщение. |
| `test_devices` | bool | Если `true`, отправка будет осуществлена только на тестовые устройства приложения. |
| `hwids` | `{ "list": [string, ...] }` | Отправка только на эти [hwids](/ru/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid). |
| `users` | `{ "list": [string, ...] }` | Отправка только на эти [User ID](/ru/developer/pushwoosh-knowledge-hub/users-userids/). |
| `push_tokens` | `{ "list": [string, ...] }` | Отправка только на эти [push-токены](/ru/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token). |
| `payload` | [`Payload`](/ru/developer/api-reference/messaging-api-v2/payload-reference/) | Полезная нагрузка (payload) для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. |
| `email_payload` | [`EmailPayload`](/ru/developer/api-reference/messaging-api-v2/email-payload-reference/) | Полезная нагрузка (payload) для Email. |
| `return_unknown_identifiers` | bool | Если `true`, в ответе поле `unknown_identifiers` будет содержать список ненайденных идентификаторов. |
| `use_latest_user_device` | bool | Применяется только при таргетинге на `users`. Если `true`, сообщение доставляется на последнее активное устройство каждого пользователя — то, у которого самое свежее время последнего открытия приложения (Last Application Open), — вместо всех устройств, связанных с этим User ID. По умолчанию `false` (отправлять на все устройства). |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | См. `NotifySegment` выше. |
`test_devices`, `hwids`, `users` и `push_tokens` взаимоисключающие. Должен быть установлен ровно один из них.
### Пример: Транзакционная отправка по User ID
```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
}
}'
```
## Ответ
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| Поле | Тип | Описание |
|---|---|---|
| `message_code` | string | Уникальный [код сообщения](/ru/developer/api-reference/api-identifiers/#message-code). Используйте его с эндпойнтами [`/getMessageDetails`](/ru/developer/api-reference/messages-api/#getmessagedetails) и статистики сообщений. |
| `unknown_identifiers` | array of string | Идентификаторы, не найденные в аккаунте. Заполняется только если в `transactional` запросе было установлено `return_unknown_identifiers: true`. |
## Общие типы
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| Поле | Тип | Описание |
|---|---|---|
| `at` | timestamp | Абсолютное время отправки (RFC 3339). Если время в прошлом, сообщение отправляется немедленно. Максимум 14 дней в будущем. |
| `after` | duration | Альтернатива `at`. Отправить через указанный промежуток времени от "сейчас" (например, `"3600s"`). |
| `follow_user_timezone` | bool | Если `true`, каждое устройство получает сообщение в `at` по своему локальному времени. |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (по умолчанию), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND` или `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. Имеет значение только если `follow_user_timezone` равно `true`. |
### FrequencyCapping
Ограничения частоты для одного пользователя для маркетинговых рассылок. Чтобы отключить ограничение, полностью опустите `frequency_capping` или отправьте `days: 0` вместе с `count: 0`.
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, или `0` для отключения ограничения): окно ретроспективного анализа. Должно отправляться вместе с `count` — если одно из полей равно `0`, другое также должно быть `0`; отправка одного поля как `0`, а другого как ненулевого значения вернет `400`.
- `count` (int, 1 или выше, или `0` для отключения ограничения): максимальное количество сообщений, разрешенное в течение `days`. То же правило парности, что и для `days` выше.
- `exclude` (bool): жесткое исключение пользователей, которые уже достигли лимита.
- `avoid` (bool): мягкое избегание пользователей, которые уже достигли лимита (они все еще учитываются в аналитике).
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
Ограничивает скорость отправки. `value` — это количество сообщений в `bucket`; типичное значение `bucket` — `"1s"`.
### Platform enum
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.
### MessageType enum
- `MESSAGE_TYPE_UNSPECIFIED`: эквивалентно `MESSAGE_TYPE_MARKETING`.
- `MESSAGE_TYPE_MARKETING`: подлежит фильтрации по контрольной группе и ограничению частоты.
- `MESSAGE_TYPE_TRANSACTIONAL`: пропускает фильтрацию по контрольной группе и ограничение частоты. Используйте для подтверждений заказов, одноразовых паролей и подобных критически важных процессов.
## Связанные материалы