Notify

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

Creates and schedules a single message.

Request structure

The request body is a NotifyRequest with exactly one of two kinds:

• segment: target an audience segment by segment code, or — without creating a segment first — a seglang expression or a structured filter expression.
• transactional: send to an explicit list of hwids, user IDs, push tokens, or test devices.

Shape

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

Field	Type	Description
transaction_id	string	Optional. Idempotency key for the request — works with both segment and transactional. A repeat call with the same transaction_id within 5 minutes returns the original message_code instead of sending a duplicate message. Use a UUID or another value unique per logical send.

Tip

Pass an X-Request-ID header to correlate the created message with your request for end-to-end tracing — see Request ID.

Only the key is checked, not the payload

Deduplication matches on transaction_id alone. If a retry reuses the same transaction_id but sends a different segment / transactional body, the original message_code is still returned and the new body is silently discarded — it is not compared against the first request. Never reuse a transaction_id across logically different messages.

Tip

This is the same deduplication mechanism as transactionId on the legacy Messages API, sharing the same 5-minute storage window, so a retried request is deduplicated across /createMessage and Notify alike. It is unrelated to the transaction_id attribute on PW_Conversion revenue events, which Pushwoosh stores as-is and does not use for deduplication.

NotifySegment

Targets users who match an audience segment or filter expression. Set exactly one of code, expression, or filter_expression. For expression and filter_expression, no segment needs to be created beforehand — the expression is evaluated inline for this send only.

Choosing between code and inline expressions

Only a saved segment referenced by code can use high-speed delivery precompilation. expression and filter_expression are evaluated at send time and are never precompiled.

Field	Type	Description
schedule	Schedule	When and how to send. Required.
application	string	Application code.
platforms	array of Platform	Platforms the message targets.
code	string	Segment code of a segment saved in advance. Mutually exclusive with expression and filter_expression.
expression	string	Seglang expression, evaluated for this send only — no saved segment required. Mutually exclusive with code and filter_expression.
filter_expression	FilterExpression	The same logic as expression, as a structured object instead of a seglang string. Mutually exclusive with code and expression. The FilterExpression schema isn’t publicly documented — request it from Pushwoosh support if you need the structured form.
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger payload. Mutually exclusive with email_payload.
email_payload	EmailPayload	Email payload.
campaign	string	Campaign code to attribute this message to.
campaign_name	string	Internal name for this message, shown as the row title in Message History and in its export. Unrelated to campaign above. It doesn’t group messages or affect delivery. Max 255 characters, trimmed. Omit it or leave it empty to keep the row titled from the payload’s own content instead.
frequency_capping	FrequencyCapping	Per-user frequency limits.
send_rate	SendRate	Throttling for the send.
message_type	MessageType	MESSAGE_TYPE_MARKETING (default) or MESSAGE_TYPE_TRANSACTIONAL. Controls control-group filtering.
dynamic_content_placeholders	map<string, string>	Replaces placeholders in content.
meta_data	object	Free-form metadata forwarded to downstream analytics.
use_latest_user_device	bool	When true, delivers the message to each user’s most recently active device (the one with the latest Last Application Open) instead of every device matched by the segment. Scoped to platforms: only devices on those platforms are considered, and if none has Last Application Open data, the first matching device is used instead of dropping the send. Defaults to false (send to every device).
control_group	string	Control group to measure this message against, by group code or name. Empty uses the application’s default control group. Mutually exclusive with holdout_percentage.
holdout_percentage	uint32	Share of this send’s audience, 1–20, held out into a one-off control group for this message only. Mutually exclusive with control_group.

Example: Send to a segment

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

Sends to an explicit list of recipients.

Field	Type	Description
schedule	Schedule	Required.
application	string	Application code.
platforms	array of Platform	Platforms the message targets.
test_devices	bool	If true, send to the app’s test devices only.
hwids	{ "list": [string, ...] }	Send to these hwids only.
users	{ "list": [string, ...] }	Send to these user IDs only.
push_tokens	{ "list": [string, ...] }	Send to these push tokens only.
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger payload.
email_payload	EmailPayload	Email payload.
return_unknown_identifiers	bool	When true, the response’s unknown_identifiers lists identifiers that were not found.
use_latest_user_device	bool	Only applies when you target users. Same behavior as in NotifySegment above — delivers one message per user instead of one per device, scoped to platforms. Defaults to false.
campaign, campaign_name, frequency_capping, send_rate, message_type, dynamic_content_placeholders, meta_data		See NotifySegment above.

test_devices, hwids, users, and push_tokens are mutually exclusive. Exactly one must be set.

Example: Transactional by user IDs

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

Response

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

Field	Type	Description
message_code	string	Unique message code. Use it with /getMessageDetails and message statistics endpoints.
unknown_identifiers	array of string	Identifiers not found on the account. Populated only when return_unknown_identifiers: true was set on the transactional kind.

Shared types

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

Field	Type	Description
at	timestamp	Absolute send time (RFC 3339). If in the past, the message is sent immediately. Maximum 14 days in the future.
after	duration	Alternative to at. Send after this offset from “now” (e.g. "3600s").
follow_user_timezone	bool	When true, each device receives the message at at in its local timezone.
past_timezones_behaviour	enum	PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY (default), PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND, or PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY. Only meaningful when follow_user_timezone is true.

FrequencyCapping

Per-user frequency limits for marketing sends. To disable capping, omit frequency_capping entirely, or send days: 0 together with count: 0.

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

• days (int, 1–30, or 0 to disable capping): look-back window. Must be sent together with count — if one is 0, the other must also be 0; sending one as 0 while the other is nonzero returns 400.
• count (int, 1 or higher, or 0 to disable capping): maximum messages allowed within days. Same pairing rule as days above.
• exclude (bool): hard-exclude users who have already hit the cap.
• avoid (bool): soft-avoid users who have already hit the cap (they still count toward analytics).

Important

Sending days and count with mismatched zero-ness (e.g. {"days": 0, "count": 5}) returns 400. This validation is a breaking change to Notify — clients that previously relied on a lone 0 being silently ignored will now get an error instead.

SendRate

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

Throttles the send. value is messages per bucket; typical bucket is "1s".

Platform enum

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

MessageType enum

• MESSAGE_TYPE_UNSPECIFIED: equivalent to MESSAGE_TYPE_MARKETING.
• MESSAGE_TYPE_MARKETING: subject to control-group filtering and frequency capping.
• MESSAGE_TYPE_TRANSACTIONAL: skips control-group filtering and frequency capping. Use for order confirmations, OTPs, and similar critical flows.

Related

Notify batch

Cancel

Payload reference

Email payload reference

Migration from v1