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

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

Выбор между кодом и встроенными выражениями

Только сохраненный сегмент, на который ссылается code, может использовать предварительную компиляцию для высокоскоростной доставки. expression и filter_expression вычисляются во время отправки и никогда не компилируются предварительно.

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

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

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 / Facebook Messenger.
email_payload	EmailPayload	Полезная нагрузка для 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

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, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

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

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

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

Пакетная отправка Notify

Отмена

Справочник по полезной нагрузке

Справочник по полезной нагрузке Email

Миграция с v1