Notify

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

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

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

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

• segment: таргетирование на сегмент аудитории по коду сегмента, выражению seglang или структурированному выражению фильтра.
• transactional: отправка по явному списку hwids, User ID, push-токенов или тестовых устройств.

Shape

{
  "segment": { ... },      // ИЛИ
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

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

Совет

Передайте заголовок X-Request-ID, чтобы сопоставить созданное сообщение с вашим запросом для сквозного отслеживания — см. Request ID.

Проверяется только ключ, а не полезная нагрузка

Дедупликация происходит только по transaction_id. Если при повторной попытке используется тот же transaction_id, но с другим телом segment / transactional, все равно будет возвращен исходный message_code, а новое тело будет молча отброшено — оно не сравнивается с первым запросом. Никогда не используйте один и тот же transaction_id для логически разных сообщений.

Совет

Это тот же механизм дедупликации, что и transactionId в устаревшем Messages API, с тем же 5-минутным окном хранения, поэтому повторный запрос будет дедуплицирован как через /createMessage, так и через Notify. Он не связан с атрибутом transaction_id в событиях дохода PW_Conversion, который Pushwoosh сохраняет как есть и не использует для дедупликации.

NotifySegment

Таргетируется на пользователей, которые соответствуют сегменту аудитории или выражению фильтра.

Поле	Тип	Описание
schedule	Schedule	Когда и как отправлять. Обязательно.
application	string	Код приложения.
platforms	array of Platform	Платформы, на которые нацелено сообщение.
code	string	Код сегмента. Взаимоисключающий с expression и filter_expression.
expression	string	Выражение Seglang.
filter_expression	FilterExpression	Структурированное выражение фильтра (расширенный).
payload	Payload	Полезная нагрузка для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Взаимоисключающий с email_payload.
email_payload	EmailPayload	Полезная нагрузка для Email.
campaign	string	Код кампании, к которой относится это сообщение.
frequency_capping	FrequencyCapping	Ограничения частоты отправки для каждого пользователя.
send_rate	SendRate	Ограничение скорости отправки.
message_type	MessageType	MESSAGE_TYPE_MARKETING (по умолчанию) или MESSAGE_TYPE_TRANSACTIONAL. Управляет фильтрацией по контрольной группе.
dynamic_content_placeholders	map<string, string>	Заменяет плейсхолдеры в контенте.
meta_data	object	Метаданные в свободной форме, передаваемые в последующие системы аналитики.

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

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	Обязательно.
application	string	Код приложения.
platforms	array of Platform	Платформы, на которые нацелено сообщение.
test_devices	bool	Если true, отправлять только на тестовые устройства приложения.
hwids	{ "list": [string, ...] }	Отправлять только на эти hwids.
users	{ "list": [string, ...] }	Отправлять только на эти User ID.
push_tokens	{ "list": [string, ...] }	Отправлять только на эти push-токены.
payload	Payload	Полезная нагрузка для Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber.
email_payload	EmailPayload	Полезная нагрузка для 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

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
    }
  }'

Ответ

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Поле	Тип	Описание
message_code	string	Уникальный код сообщения. Используйте его с эндпоинтами /getMessageDetails и статистики сообщений.
unknown_identifiers	array of string	Идентификаторы, не найденные в аккаунте. Заполняется только в том случае, если в transactional-запросе было установлено return_unknown_identifiers: true.

Общие типы

Schedule

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

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

Важно

Отправка days и count с несоответствующими нулевыми значениями (например, {"days": 0, "count": 5}) вернет 400. Эта проверка является критическим изменением в Notify — клиенты, которые ранее полагались на то, что одиночный 0 будет молча игнорироваться, теперь получат ошибку.

SendRate

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

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

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

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

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

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

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

Отмена

Справочник по Payload

Справочник по Email Payload

Миграция с v1