# Notify

`POST` `https://api.pushwoosh.com/messaging/v2/notify`

Создает и планирует отправку одного сообщения.

<span id="request-structure" />

## Структура запроса

Тело запроса — это `NotifyRequest` с одним из двух видов:

- [`segment`](#notifysegment): нацеливание на сегмент аудитории по коду сегмента или — без предварительного создания сегмента — на выражение [seglang](/ru/developer/api-reference/segmentation-filters-api/segmentation-language/) или структурированное выражение фильтра.
- [`transactional`](#notifytransactional): отправка по явному списку hwids, User ID, push-токенов или тестовых устройств.

```json title="Shape"
{
  "segment": { ... },      // ИЛИ
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}
```

| Поле | Тип | Описание |
|---|---|---|
| `transaction_id` | string | Необязательно. Ключ идемпотентности для запроса — работает как с `segment`, так и с `transactional`. Повторный вызов с тем же `transaction_id` в течение 5 минут возвращает исходный `message_code` вместо отправки дублирующего сообщения. Используйте UUID или другое уникальное значение для каждой логической отправки. |

<Aside type="tip">
Передайте заголовок `X-Request-ID`, чтобы сопоставить созданное сообщение с вашим запросом для сквозного отслеживания — см. [Request ID](/ru/developer/api-reference/api-identifiers/#request-id).
</Aside>

<Aside type="caution" title="Проверяется только ключ, а не полезная нагрузка">
Дедупликация происходит только по `transaction_id`. Если при повторной попытке используется тот же `transaction_id`, но отправляется другое тело `segment` / `transactional`, все равно возвращается исходный `message_code`, а новое тело молча отбрасывается — оно не сравнивается с первым запросом. Никогда не используйте один и тот же `transaction_id` для логически разных сообщений.
</Aside>

<Aside type="tip">
Это тот же механизм дедупликации, что и `transactionId` в устаревшем [Messages API](/ru/developer/api-reference/messages-api/), с тем же 5-минутным окном хранения, поэтому повторный запрос дедуплицируется как через `/createMessage`, так и через `Notify`. Он не связан с атрибутом `transaction_id` в событиях дохода [`PW_Conversion`](/ru/product/audience-data-and-segmentation/events/conversion-events/#attributes-for-the-postevent-call), который Pushwoosh хранит как есть и не использует для дедупликации.
</Aside>

## NotifySegment

Нацеливается на пользователей, которые соответствуют сегменту аудитории или выражению фильтра. Установите ровно одно из полей: `code`, `expression` или `filter_expression`. Для `expression` и `filter_expression` не требуется предварительно создавать сегмент — выражение вычисляется "на лету" только для этой отправки.

<Aside type="note" title="Выбор между кодом и встроенными выражениями">
Только сохраненный сегмент, на который ссылается `code`, может использовать предварительную компиляцию для [высокоскоростной доставки](/ru/product/resources/high-speed-delivery/). `expression` и `filter_expression` вычисляются во время отправки и никогда не компилируются предварительно.
</Aside>

| Поле | Тип | Описание |
|---|---|---|
| `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/), вычисляемое только для этой отправки — сохраненный сегмент не требуется. Взаимоисключающий с `code` и `filter_expression`. |
| `filter_expression` | `FilterExpression` | Та же логика, что и у `expression`, но в виде структурированного объекта, а не строки seglang. Взаимоисключающий с `code` и `expression`. Схема `FilterExpression` не документирована публично — запросите ее у службы поддержки Pushwoosh, если вам нужна структурированная форма. |
| `payload` | [`Payload`](/ru/developer/api-reference/messaging-api-v2/payload-reference/) | Полезная нагрузка для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. Взаимоисключающий с `email_payload`. |
| `email_payload` | [`EmailPayload`](/ru/developer/api-reference/messaging-api-v2/email-payload-reference/) | Полезная нагрузка для Email. |
| `campaign` | string | [Код кампании](/ru/developer/api-reference/api-identifiers/#campaign-code), к которой относится это сообщение. |
| `campaign_name` | string | Внутреннее название этого сообщения, отображается как заголовок строки в Message History и в её экспорте. Не связано с `campaign` выше. Оно не группирует сообщения и не влияет на доставку. Максимум 255 символов, обрезается. Не указывайте это поле или оставьте его пустым, чтобы заголовок строки формировался из содержимого полезной нагрузки. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Ограничения частоты для каждого пользователя. |
| `send_rate` | [`SendRate`](#sendrate) | Ограничение скорости отправки. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (по умолчанию) или `MESSAGE_TYPE_TRANSACTIONAL`. Управляет фильтрацией по контрольной группе. |
| `dynamic_content_placeholders` | map&lt;string, string&gt; | Заменяет плейсхолдеры в контенте. |
| `meta_data` | object | Метаданные в свободной форме, передаваемые в последующие системы аналитики. |
| `use_latest_user_device` | bool | Если `true`, доставляет сообщение на последнее активное устройство каждого пользователя (то, у которого самое свежее время последнего открытия приложения), а не на каждое устройство, соответствующее сегменту. Ограничено `platforms`: учитываются только устройства на этих платформах, и если ни у одного из них нет данных о последнем открытии приложения, используется первое подходящее устройство, а не отменяется отправка. По умолчанию `false` (отправлять на каждое устройство). |
| `control_group` | string | Код или название собственной удерживаемой группы отправки, применяемой к этому сообщению. Не сужает набор [контрольных групп](/ru/product/audience-data-and-segmentation/control-groups/), которые действуют: каждая включённая контрольная группа приложения удерживает пользователей от маркетинговых отправок независимо от того, задано ли это поле. Взаимоисключающее с `holdout_percentage`. |
| `holdout_percentage` | uint32 | Доля аудитории этой отправки (1–20), удерживаемая в разовой контрольной группе только для этого сообщения. Взаимоисключающее с `control_group`. |

### Пример: Отправка сегменту

```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/) | Полезная нагрузка для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. |
| `email_payload` | [`EmailPayload`](/ru/developer/api-reference/messaging-api-v2/email-payload-reference/) | Полезная нагрузка для Email. |
| `return_unknown_identifiers` | bool | Если `true`, поле `unknown_identifiers` в ответе будет содержать список ненайденных идентификаторов. |
| `use_latest_user_device` | bool | Применяется только при нацеливании на `users`. Поведение такое же, как в `NotifySegment` выше — доставляет одно сообщение на пользователя, а не на устройство, в рамках `platforms`. По умолчанию `false`. |
| `campaign`, `campaign_name`, `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
    }
  }'
```

<span id="response" />

## Ответ

```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). Если время в прошлом, Pushwoosh подставляет время получения запроса. Если `follow_user_timezone` не задан или равен `false`, это означает, что сообщение уходит всем немедленно. О случае `follow_user_timezone: true` см. предупреждение ниже. Максимум на 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`. |

<Aside type="caution" title="Время отправки в прошлом не означает мгновенную отправку всем при follow_user_timezone">
При `follow_user_timezone: true` подставленное «сейчас» всё равно разбивается на слоты по локальному времени устройств и не доставляется на все устройства сразу. В часовых поясах, отстающих от UTC, этот момент ещё не наступил, поэтому сообщение приходит там с задержкой до 12 часов. В часовых поясах, опережающих UTC, этот момент по местному времени уже прошёл, поэтому для них действует `past_timezones_behaviour`: отправить сейчас, пропустить (`DO_NOT_SEND`) или перенести на день вперёд (`NEXT_DAY`) в то же локальное время.
</Aside>

### 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): мягко избегать пользователей, которые уже достигли лимита (они все равно учитываются в аналитике).

<Aside type="caution" title="Важно">
Отправка `days` и `count` с несоответствующими нулевыми значениями (например, `{"days": 0, "count": 5}`) вернет ошибку `400`. Эта проверка является критическим изменением для `Notify` — клиенты, которые ранее полагались на то, что одиночный `0` будет молча игнорироваться, теперь получат ошибку.
</Aside>

### SendRate

```json
{ "value": 500, "bucket": "1s", "avoid": false }
```

Ограничивает скорость отправки. `value` — это количество сообщений в `bucket`; типичный `bucket` — `"1s"`.

<span id="platform-enum" />

### Перечисление Platform

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

<span id="messagetype-enum" />

### Перечисление MessageType

- `MESSAGE_TYPE_UNSPECIFIED`: эквивалентно `MESSAGE_TYPE_MARKETING`.
- `MESSAGE_TYPE_MARKETING`: подлежит фильтрации по контрольной группе и ограничению частоты.
- `MESSAGE_TYPE_TRANSACTIONAL`: пропускает фильтрацию по контрольной группе и ограничение частоты. Используйте для подтверждений заказов, одноразовых паролей и подобных критически важных процессов.

## Связанные материалы

<CardGrid>
  <LinkCard title="Пакетная отправка Notify" href="/developer/api-reference/messaging-api-v2/notify-batch/" />
  <LinkCard title="Отмена" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Справочник по полезной нагрузке" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="Справочник по полезной нагрузке Email" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Миграция с v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>