Notify

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

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

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

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

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

Shape

{
  "segment": { ... }       // ИЛИ
  "transactional": { ... }
}

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. Взаимоисключающий с 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, ...] }	Отправить только на эти hwid.
users	{ "list": [string, ...] }	Отправить только этим User ID.
push_tokens	{ "list": [string, ...] }	Отправить только на эти push-токены.
payload	Payload	Полезная нагрузка для Push / SMS / Telegram / Kakao.
email_payload	EmailPayload	Полезная нагрузка для Email.
return_unknown_identifiers	bool	Если true, поле unknown_identifiers в ответе будет содержать список ненайденных идентификаторов.
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
    }
  }'

Ответ

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

Ограничения по частоте для каждого пользователя для маркетинговых рассылок.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30): окно ретроспективного анализа.
• count (int): максимальное количество сообщений, разрешенное в течение days.
• exclude (bool): жесткое исключение пользователей, которые уже достигли лимита.
• avoid (bool): мягкое избегание пользователей, которые уже достигли лимита (они все еще учитываются в аналитике).

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.

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

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

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

Справка по Payload

Справка по Email Payload

Миграция с v1