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 (отправлять на каждое устройство).
control_group	string	Код или название собственной удерживаемой группы отправки, применяемой к этому сообщению. Не сужает набор контрольных групп, которые действуют: каждая включённая контрольная группа приложения удерживает пользователей от маркетинговых отправок независимо от того, задано ли это поле. Взаимоисключающее с holdout_percentage.
holdout_percentage	uint32	Отбирает эту долю сегмента (от 1 до 20) в контрольную группу, действующую только для этой отправки, в дополнение к включённым контрольным группам приложения, чтобы измерить эффект одной кампании, не расходуя общие группы. 0 (по умолчанию) отключает отбор. Взаимоисключающее с control_group.

Важно

Pushwoosh называет удерживаемую группу __holdout_<campaign code> (или __holdout_<message code> для отправки без campaign) и повторно использует ту же группу с исходным процентом для каждой последующей отправки с тем же кодом. Состав группы фиксируется при её первом создании. Эта группа никогда не отображается в разделе Настройки > Контрольные группы, а попытка изменить её размер, перемешать, отключить или удалить возвращает FailedPrecondition, поскольку изменение посреди измерения сделало бы сравнение недействительным.

Устройства, отобранные в удерживаемую группу, исключаются из доставки так же, как контрольными группами приложения. Сообщение им не отправляется, а журнал отслеживания фиксирует отсев как Device is in control group. При message_type, равном MESSAGE_TYPE_TRANSACTIONAL, это исключение полностью пропускается — так же, как для контрольных групп приложения.

Если задать holdout_percentage вместе с control_group или указать holdout_percentage больше 20, возвращается 400:

Invalid holdout_percentage

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

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

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). Если время в прошлом, Pushwoosh подставляет время получения запроса. Если follow_user_timezone не задан или равен false, это означает, что сообщение уходит всем немедленно. О случае follow_user_timezone: true см. предупреждение ниже. Максимум на 30 дней в будущем.
after	duration	Альтернатива at. Отправить через указанный промежуток времени от “сейчас” (например, "3600s"). Максимум 30 дней.
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 или задан best_time_to_send.
best_time_to_send	timestamp	Необязательно. Только для отправок сегменту. Каждое устройство получает сообщение в свой лучший час в течение 24 часов от этого времени. Устройства без лучшего часа получают его в дату и время из at / after по своему локальному часовому поясу. См. Лучшее время отправки.

Время отправки в прошлом не означает мгновенную отправку всем при follow_user_timezone

При follow_user_timezone: true подставленное «сейчас» всё равно разбивается на слоты по локальному времени устройств и не доставляется на все устройства сразу. В часовых поясах, отстающих от UTC, этот момент ещё не наступил, поэтому сообщение приходит там с задержкой до 12 часов. В часовых поясах, опережающих UTC, этот момент по местному времени уже прошёл, поэтому для них действует past_timezones_behaviour: отправить сейчас, пропустить (DO_NOT_SEND) или перенести на день вперёд (NEXT_DAY) в то же локальное время. То же разбиение применяется к резервной отправке при best_time_to_send.

Лучшее время отправки

best_time_to_send — это API-аналог опции Лучшее время в Control Panel. at / after задаёт резервную отправку для устройств, по которым недостаточно данных для определения лучшего часа. Pushwoosh берёт дату и время at / after в UTC и доставляет резервную отправку в эту дату и время по локальному часовому поясу каждого устройства, как при follow_user_timezone: true. Это применяется неявно: не задавайте follow_user_timezone, поскольку значение true отклоняется с BestTimeToSendWithUserTimezone. В примере ниже устройства без лучшего часа получат сообщение 1 мая в 18:00 по местному времени. Там, где это местное время на момент начала отправки уже прошло, действует past_timezones_behaviour.

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

Pushwoosh отклоняет запрос с 400, если не выполнены все следующие условия:

• Запрос использует вид segment. Отправки transactional не поддерживают best_time_to_send.
• follow_user_timezone не задан или равен false.
• Время отправки из at / after находится в будущем. Прошедшее at, after: "0s" или отсутствующий after считаются «отправить сейчас» и отклоняются.
• best_time_to_send не раньше следующего полного часа и не более чем на 30 дней вперёд. Значение округляется вниз до полного часа.
• Время отправки из at / after не позже best_time_to_send плюс 24 часа.

Поле reason ошибки (в детали ErrorInfo) указывает, какая проверка не пройдена:

reason	Причина
BestTimeToSendWithUserTimezone	follow_user_timezone равно true.
BestTimeToSendTooEarly	best_time_to_send раньше следующего полного часа.
BestTimeToSendTooFarInFuture	best_time_to_send более чем на 30 дней вперёд.
SendDateAfterBestTimeToSend	at / after позже best_time_to_send плюс 24 часа.
BestTimeToSendNotAllowed	best_time_to_send задан для отправки transactional.
BestTimeToSendWithSendNow	at / after означает «сейчас» (прошедшее at или нулевой after).

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