Messages

API methods to manage push messages

post
/createMessage

https://cp.pushwoosh.com/json/1.3/createMessage
Creates a new push notification.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
application
required
string
Pushwoosh application code.
notifications
required
array
JSON array of message parameters. See details in a request example below.
200: OK
{
"status_code":200,
"status_message":"OK"
}

Request example

Example
{
"request": {
"application": "XXXXX-XXXXX", // Pushwoosh application code
"applications_group": "GROUP_CODE", // optional. Can be used instead of "application".
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"notifications": [
{
// Content settings
"send_date": "now", // required. YYYY-MM-DD HH:mm OR 'now'
"ignore_user_timezone": true, // or false, required
"timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". See http://php.net/manual/timezones.php for supported timezones.
"campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to assign this push message.
"geozone": { // optional, send to Geozone
"lat": 22.22,
"lng": 33.33,
"range": 110
},
"content": { // required, object( language1: 'content1', language2: 'content2' ) OR string. Ignored for Windows 8, use "wns_content" instead. (Use \n for multiline text. Ex: "hello\nfriend")
"en": "English",
"ru": "Русский",
"de": "Deutsch"
},
"page_id": 39, // optional, integer. HTML Page ID.
"rich_media": "XXXXX-XXXXX", // optional, string. Copy the Rich Media code from the URL bar of the Rich Media editor page in Pushwoosh Control Panel.
"remote_page": "http://myremoteurl.com", // optional, string. Remote Rich HTML Page URL. <scheme>://<authority>
"link": "http://google.com", // optional, string. For deeplinks add "minimize_link":0
"minimize_link": 0, // optional. 0 — do not minimize, 2 — bitly. Default = 2. Google URL shortener is disabled since March 30, 2019. Please note that shorteners have restrictions on a number of calls.
"data": {
"key": "value" // optional, JSON string or JSON object, will be passed as "u" parameter in the payload (converted to JSON string).
},
"transactionId": "6e22a9af-84e4-46e6-af16-e457a4a6e7e5", // optional, string. Unique message identifier to prevent duplicating in case of network problems. Stored on the side of Pushwoosh for 1 day.
"platforms": [1,2,3,5,7,8,9,10,11,12,13], // optional. 1 — iOS; 2 — BB; 3 — Android; 5 — Windows Phone; 7 — OS X; 8 — Windows 8; 9 — Amazon; 10 — Safari; 11 — Chrome; 12 — Firefox; 13 - IE11; ignored if "devices" < 10
"preset": "Q1A2Z-6X8SW", // optional. Push Preset Code from your Control Panel.
"send_rate": 100, // optional. Throttling. Valid values are from 100 to 1000 pushes/second.
// Frequency capping params
"capping_days": 30, // Amount of days for frequency capping (max 30 days)
"capping_count": 10, // The max number of pushes that can be sent from a specific app to a particular device within a 'capping_days' period. In case the message created exceeds the 'capping_count' limit for a device, it won't be sent to that device.
// To save the message to the Inbox via API, use "inbox_date" or "inbox_image". The message is saved when at least one of these parameters is used.
"inbox_date": "2017-02-02", // optional. Specify when to remove a message from the Inbox. If not specified, the default removal date is the next day after the send date.
"inbox_image": "Inbox image URL", // optional. The image to be shown near the message.
"devices": [ // optional. Specify tokens or hwids to send targeted push notifications. Not more than 1000 tokens/hwids in an array. If set, the message will only be sent to the devices on the list. Application Group for devices list is not allowed. iOS push tokens can only be lower case.
"dec301908b9ba8df85e57a58e40f96f523f4c2068674f5fe2ba25cdc250a2a41"
],
// user-centric push notifications
"users": [ // optional. If set, message will only be delivered to the specified user ID's (set via /registerUser call). If specified together with devices parameter, the latter will be ignored. Not more than 1000 user ID's in an array.
"user_3078a"
],
//filters and conditions
"filter": "FILTER_NAME", // optional
"dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tags.
"firstname": "John",
"lastname": "Doe"
},
"conditions": [TAG_CONDITION1, TAG_CONDITION2, ..., TAG_CONDITIONN] // optional. See the remark below.
}
]
}
}

Platform-specific parameters

iOS

Example
"ios_badges": 5, // optional, integer. iOS application badge number. Use "+n" or "-n" to increment/decrement the badge value by n.
"ios_sound": "sound file.wav", // optional. Sound file name in the main bundle of application. If left empty, the device will produce no sound upon receiving a push.
"ios_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds.
"ios_silent": 1, // optional. Enables silent notifications (ignore "sound" and "content").
"ios_category_id": "1", // optional, integer. iOS8 category ID from Pushwoosh.
"ios_root_params" : { // optional. Root level parameters to the aps dictionary.
"aps":{
"content-available": "1",
"mutable-content":1 // required for iOS 10 Media attachments.
},
"attachment":"YOUR_ATTACHMENT_URL",
"data": << User supplied data, max of 4KB>>
},
"apns_trim_content": 1, // optional. (0|1) Trims the exceeding content strings with ellipsis.
"ios_trim_content": 1, // Deprecated, use "apns_trim_content" instead.
"ios_title":"Title", // optional. Adds Title for push notification.
"ios_subtitle" : "SubTitle", // optional. Adds sub-title for push notification.
"ios_thread_id": "some thread id", // optional, string. Identifier to group related notifications. Messages with the same thread ID will be grouped on the lock screen and in the Notification Center.
"ios_critical": true // optional. Marks iOS notification as a critical alert playing sound even if a device is muted or Do Not Disturb mode is on.

Android

Example
"android_root_params": {"key": "value"}, // optional. Custom key-value object. Root level parameters for the android payload recipients.
"android_sound" : "soundfile", // optional. No file extension. If left empty, the device will produce no sound upon receiving a push.
"android_header": "header", // optional. Android notification header.
"android_icon": "icon.png",
"android_custom_icon": "http://example.com/image.png", // optional. Full path URL to the image file.
"android_banner": "http://example.com/banner.png", // optional. Full path URL to the image file.
"android_badges": 5, // optional, integer. Android application icon badge number. Use "+n" or "-n" to increment/decrement the badge value by n.
"android_gcm_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds.
"android_vibration": 0, // boolean. Android force-vibration for high-priority pushes.
"android_led": "#rrggbb", // LED hex color, device will do its best approximation.
"android_priority": -1, // Sets the “importance” parameter for devices with Android 8.0 and higher, as well as the “priority” parameter for devices with Android 7.1 and lower. Establishes the interruption level of a notification channel or a particular notification. Valid values are -2, -1, 0, 1, 2.
"android_delivery_priority": "normal", // or "high", optional. Enables notification’s delivery when the device is in the power saving mode.
"android_ibc": "#RRGGBB", // icon background color on Lollipop, #RRGGBB, #AARRGGBB, "red", "black", "yellow", etc.
"android_silent": 1 // optional. 0 or 1, enable silent notificaiton (ignore sound and content).

Safari

Safari
"safari_title": "Title", // obligatory. Title of the notification.
"safari_action": "Click here", // optional
"safari_url_args": ["firstArgument", "secondArgument"], // obligatory, but the value may be empty
"safari_ttl": 3600 // optional. Time to live parameter — the maximum lifespan of a message in seconds.

Chrome parameters

Chrome
"chrome_title": "Title", // optional. You can specify the header of the message in this parameter.
"chrome_icon": "icon_URL", // full path URL to the icon or extension resources file path
"chrome_gcm_ttl": 3600, // optional. Time to live parameter – maximum message lifespan in seconds.
"chrome_duration": 20, // optional. Changes chrome push display time. Set to 0 to display push until user interacts with it.
"chrome_image": "image_URL", // optional. URL to large image.
"chrome_root_params": {"key":"value"}, // optional. Set parameters specific to messages sent to Chrome.
"chrome_button_text1": "1", // optional
"chrome_button_url1": "button1_URL", // optional. Ignored if chrome_button_text1 is not set.
"chrome_button_text2": "2", // optional
"chrome_button_url2": "button2_url" // optional. Ignored if chrome_button_text2 is not set.

Firefox parameters

Firefox
"firefox_title": "Title", // optional. You can specify message header here.
"firefox_icon": "icon_URL", // full path URL to the icon or path to the file in extension resources.
"firefox_root_params": {"key":"value"} // optional. Set parameters specific to messages sent to Firefox.

Amazon parameters

Amazon
"adm_root_params": {"key":"value"}, // custom key-value object
"adm_sound": "push.mp3",
"adm_header": "Header",
"adm_icon": "icon",
"adm_custom_icon": "http://example.com/image.png",
"adm_banner": "http://example.com/banner.png",
"adm_ttl": 3600, // optional. Time to live parameter — the maximum message lifespan in seconds.
"adm_priority":-1 // priority of the push in Amazon push drawer, valid values are -2, -1, 0, 1 and 2.

Windows Phone parameters

Windows Phone
"wp_type": "Tile", // Windows Phone notification type. 'Tile' or 'Toast'. Raw notifications are not supported. 'Tile' is default.
"wp_background": "/Resources/Red.jpg", // tile image
"wp_backbackground": "/Resources/Green.jpg", // back tile image
"wp_backtitle": "back title", // back tile title
"wp_backcontent": "back content", // back tile content
"wp_count": 3 // optional, integer. Badge for Windows Phone notification.

Mac OS X parameters

Mac OS X
"mac_badges": 3,
"mac_sound": "sound.caf",
"mac_root_params": {"content-available":1},
"mac_ttl": 3600 // optional. Time to live parameter — maximum message lifespan in seconds.

Windows parameters

Windows
"wns_content": { // Content (XML or raw) of notification encoded in MIME's base64 in form of Object( language1: 'content1', language2: 'content2' ) OR String
"en": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9ImF2YWlsYWJsZSIvPg==",
"de": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9Im5ld01lc3NhZ2UiLz4="
},
"wns_type": "Badge", // 'Tile' | 'Toast' | 'Badge' | 'Raw'
"wns_tag": "myTag", // optional. Used in Tile replacement policy. An alphanumeric string of no more than 16 characters.
"wns_cache": 1, // optional. (1|0) Translates into X-WNS-Cache-Policy value.
"wns_ttl": 600 // optional. Expiration time for notification in seconds.

/createMessage Throttling

Keep in mind that non-enterprise accounts cannot send more than 600 /createMessage and/or /createTargetedMessage requests per minute.

However, if you send pushes via the devices parameter to 10 devices or less, there are no restrictions for any account type as long as the debug mode is disabled.

Note that we always save scheduled pushes to the Message History, even if you are sending them to less than 10 devices via devices parameter. Therefore, such pushes are also throttled.

Response:

HTTP Status code

status_code

Description

200

200

Message successfully created

200

210

Argument error. See status_message for more info

400

N/A

Malformed request string

500

500

Internal error

An error in an array of notifications

If the createMessage request has several messages in the notifications array, they will be processed and sent one by one. If one of the messages cannot be parsed, our API will return "status_code":210 with the codes of successfully sent messages, i.e. those preceding the faulty message in the request.

Debug Mode

For load balancing purposes we do not store messages sent through API with the “devices” parameter that contains less than 10 devices in an array. Due to this, such messages will not be displayed in your Message History.

To see push reports during the testing phase, there’s Debug Mode. Turning Debug Mode ON allows you to override this limit for 1 hour and save such pushes in the Message History. Debug mode turns OFF automatically after 1 hour.

Debug Mode can be activated on the Message History page by switching the toggle in the upper right corner.

If the Debug Mode is turned OFF, and you send a createMessage request with less than 10 device tokens to Pushwoosh API, the server will return a “CODE_NOT_AVAILABLE” value for “Messages”, and an empty key for Unknown Devices instead of Message Code unless the message is scheduled to be sent in the future with the "send_date" parameter.

Tag conditions

Each tag condition is an array like [tagName, operator, operand] where

  • tagName: name of a tag

  • operator: "EQ" | "IN" | "NOTEQ" | "NOTIN" | "LTE" | "GTE" | "BETWEEN" | "NOTSET" | "ANY"

  • operand: string | integer | array | date

Operator description

  • EQ: tag value is equal to operand;

  • IN: tag value intersects with operand (operand must always be an array);

  • NOTEQ: tag value is not equal to an operand;

  • NOTIN: tag value does not intersect with operand (operand must always be an array);

  • GTE: tag value is greater than or equal to operand;

  • LTE: tag value is less than or equal to operand;

  • BETWEEN: tag value is greater than or equal to min operand value but less than or equal to max operand value (operand must always be an array);

  • NOTSET: tag not set. Operand is not considered;

  • ANY: tag has any value. Operand is not considered.

String tags

Valid operators: EQ, IN, NOTEQ, NOTIN, NOTSET, ANY Valid operands:

  • EQ, NOTEQ: operand must be a string;

  • IN, NOTIN: operand must be an array of strings like ["value 1", "value 2", "value N"];

  • NOTSET: tag not set. Operand is not considered;

  • ANY: tag has any value. Operand is not considered.

Integer tags

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY Valid operands:

  • EQ, NOTEQ, GTE, LTE: operand must be an integer;

  • IN, NOTIN: operand must be an array of integers like [value 1, value 2, value N];

  • BETWEEN: operand must be an array of integers like [min_value, max_value];

  • NOTSET: tag not set. Operand is not considered;

  • ANY: tag has any value. Operand is not considered.

Date tags

Valid operators: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY Valid operands:

  • "YYYY-MM-DD 00:00" (string)

  • unix timestamp 1234567890 (integer)

  • "N days ago" (string) for operators EQ, BETWEEN, GTE, LTE

Boolean tags

Valid operators: EQ, NOTSET, ANY Valid operands: 0, 1, true, false

List tags

Valid operators: IN, NOTIN, NOTSET, ANY Valid operands: operand must be an array of strings like ["value 1", "value 2", "value N"].

Remember that “filter” and “conditions” parameters should not be used together. Also, both of them will be ignored, if the "devices" parameter is used in the same request.

Country and Language tags

Language tag value is a lowercase two-letter code according to ISO-639-1 Country tag value is an UPPERCASE two-letter code according to ISO_3166-2 For example, to send push a notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

/createMessage snippets

Important!

Please be careful when using the snippets. Limit the number of recipients by specifying “users”, “devices”, “filter”, or “conditions” parameter. If none of these parameters is specified, the message will be sent to every device subscribed to push notifications from the application.

Sample /createMessage requests:

Bash
PHP
Erlang
Ruby
Java
Python
.NET
Go
JavaScript
#!/bin/bash
#Usage
if [ ! -n "$1" ] || [ ! -n "$2" ]
then
echo "`basename $0` usage: api_token appid message";
exit 1;
fi;
MESSAGE="$3";
if [ -z "$3" ]
then
MESSAGE='One push to rule them all!'
fi;
echo -e "Response:"
curl --data-binary "
{\"request\":
{\"application\":\"$2\",
\"auth\":\"$1\",
\"notifications\":
[{
\"send_date\": \"now\",
\"content\": \"$MESSAGE\"
}]
}
}" \
-H "Content-type: application/json" \
"https://cp.pushwoosh.com/json/1.3/createMessage"
echo "";
exit 0;

post
/deleteMessage

https://cp.pushwoosh.com/json/1.3/deleteMessage
Deletes a scheduled message.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
message
required
string
Message code obtained in /createMessage request.
200: OK
{
"status_code":200,
"status_message":"OK"
}
Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"message": "xxxx-xxxxxxx-xxxxxx" // message code obtained in /createMessage
}
}

You can't delete messages that have already been sent out.

Status codes:

HTTP Status code

status_code

Description

200

200

Message successfully deleted

200

210

Argument error. See status_message for more info

400

N/A

Malformed request string

500

500

Internal error

<?php
// see http://gomoob.github.io/php-pushwoosh/delete-message.html
use Gomoob\Pushwoosh\Model\Request\DeleteMessageRequest;
// creates request instance
$request = DeleteMessageRequest::create()->setMessage('MESSAGE_CODE');
// call '/deleteMessage' Web Service
$response = $pushwoosh->deleteMessage($request);
if($response->isOk()) {
print 'Great, my message has been deleted !';
} else {
print 'Oups, the deletion failed :-(';
print 'Status code : ' . $response->getStatusCode();
print 'Status message : ' . $response->getStatusMessage();
}

post
/getMessageDetails

https://cp.pushwoosh.com/json/1.3/getMessageDetails
Retrieves the message details.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
message
required
string
Message code or message ID.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"message": {
"id": 2068991743,
"created": "2016-09-14 17:19:42",
"send_date": "2016-09-14 17:19:41",
"status": "done",
"content": {
"en": "Hello {Name|CapitalizeFirst|friend}! 🚀"
},
"platforms": "[1]",
"ignore_user_timezone": "1",
"code": "XXXX-92B4C3C5-A7F5EF70"
}
}
}
Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"message": "xxxx-xxxxxxx-xxxxxx" // message code or message ID
}
}

post
/createTargetedMessage

https://cp.pushwoosh.com/json/1.3/createTargetedMessage
Creates a new targeted push notification.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
devices_filter
required
string
See remark below.
send_date
required
string
YYYY-MM-DD HH:mm or 'now'.
ignore_user_timezone
required
boolean
If ignored, UTC-0 is default for "send_date".
timezone
optional
string
If ignored, UTC-0 is default for "send_date".
campaign
optional
string
Code of a campaign to which you want to assign this push message.
content
required
string
Notification content. See the request example for details.
transactionId
optional
string
Unique message identifier to prevent duplicating messages in case of network problems. Stored on the side of Pushwoosh for 1 day.
page_id
optional
string
HTML page ID to be attached to the push message.
rich_page_id
optional
string
Rich Media code to be attached to the push message.
remote_page
optional
string
Remote Rich HTML Page URL.
link
optional
string
Link to be opened once a user opens a push message.
minimize_link
optional
integer
0 - do not minimize, 2 - bit.ly. Default = 2.
data
optional
object
JSON string or JSON object. Will be passed as "u" parameter in the payload (converted to JSON string).
preset
optional
string
Preset code.
send_rate
optional
integer
Throttling. Valid values are from 100 to 1000 pushes per second.
inbox_date
optional
string
Specify when to remove a message from the Inbox.
inbox_image
optional
string
URL of the image to be shown near the message in the Inbox.
200: OK

Hard mode

Should you be using /createMessage instead?

The method is intended for advanced targeting of your messages, and can be used for sending messages across several or all of your apps. If you do not include Application Code in your device filters, the message will be sent to any device registered in your account, that fits the Tag condition. Please make sure that you target proper applications in order to avoid sending test pushes to the production application.

Example
Platform-specific parameters
Example
{
"request": {
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"devices_filter": "FILTER CONDITION",
"send_date": "now", // YYYY-MM-DD HH:mm OR 'now'
"ignore_user_timezone": true, // or false
"timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". See http://php.net/manual/timezones.php for supported timezones.
"campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to assign this push message.
"content": { // object( language1: 'content1', language2: 'content2' ) OR string. Ignored for Windows 8, use "wns_content" instead. (Use \n for multiline text. Ex: "hello\nfriend")
"en": "English",
"ru": "Русский",
"de": "Deutsch"
},
"transactionId": "6e22a9af-84e4-46e6-af16-e457a4a6e7e5", // optional, string. Unique message identifier to prevent duplicating messages in case of network problems. Stored on the side of Pushwoosh for 1 day.
"page_id": 39, // optional, integer. HTML Page ID.
"rich_page_id": 42, // optional, integer. Rich Page ID.
"rich_media": "XXXXX-XXXXX", // optional, string. Copy the Rich Media code from the URL bar of the Rich Media editor page in Pushwoosh Control Panel.
"remote_page": "http://myremoteurl.com", // optional, string. Remote Rich HTML Page URL. <scheme>://<authority>
"link": "http://google.com", // optional, string. For deeplinks add "minimize_link":0
"minimize_link": 0, // optional. 0 — do not minimize, 2 — bitly. Default = 2. Google URL shortener is disabled since March 30, 2019. Please note that shorteners have restrictions on a number of calls.
"data": {
"key": "value" // JSON string or JSON object, will be passed as "u" parameter in the payload (converted to JSON string).
},
"preset": "Q1A2Z-6X8SW", // optional. Push Preset Code from your Control Panel.
"send_rate": 100, // throttling. Valid values are from 100 to 1000 pushes/second.
// To save the message to the Inbox via API, use "inbox_date" or "inbox_image". The message is saved when at least one of these parameters is used.
"inbox_date": "2017-02-02", // optional. Specify when to remove a message from the Inbox. If not specified, the default removal date is the next day after the send date.
"inbox_image": "Inbox image URL", // optional. The image to be shown near the message.
"dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tags.
"firstname": "John",
"lastname": "Doe"
}
}
}
Platform-specific params
{
"request": {
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"devices_filter": "FILTER CONDITION",
"send_date": "now", // YYYY-MM-DD HH:mm OR 'now'
"ignore_user_timezone": true, // or false
"timezone": "America/New_York", // optional. If ignored UTC-0 is default for "send_date". See http://php.net/manual/timezones.php for supported timezones.
"campaign": "CAMPAIGN_CODE", // optional. Campaign code to which you want to assign this push message.
"content": { // object( language1: 'content1', language2: 'content2' ) OR string. Ignored for Windows 8, use "wns_content" instead. (Use \n for multiline text. Ex: "hello\nfriend")
"en": "English",
"ru": "Русский",
"de": "Deutsch"
},
// iOS related
"ios_badges": 5, // optional, integer. iOS application badge number. Use "+n" or "-n" to increment/decrement the badge value by n.
"ios_sound": "sound file.wav", // optional. Sound file name in the main bundle of application. If left empty, the device will produce no sound upon receiving a push.
"ios_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds.
"ios_silent": 1, // optional. Enables silent notifications (ignore "sound" and "content").
"ios_category_id": "1", // optional, integer. iOS8 category ID from Pushwoosh.
"ios_root_params": { // optional. Root level parameters to the aps dictionary.
"aps": {
"content-available": "1",
"mutable-content": 1 // required for iOS 10 Media attachments.
},
"attachment": "YOUR_ATTACHMENT_URL", // iOS 10 media attachment URL.
"data": << User supplied data, max of 4KB>>
},
"apns_trim_content": 1, // optional. (0|1) Trims the exceeding content strings with ellipsis.
"ios_trim_content": 1, // Deprecated, use "apns_trim_content" instead.
"ios_title": "Title", // optional. Adds Title for push notification.
"ios_subtitle": "SubTitle", // optional. Adds sub-title for push notification.
// Android related
"android_root_params": { // optional. Custom key-value object. Root level parameters for the android payload recipients.
"key": "value"
},
"android_sound": "soundfile", // optional. No file extension. If left empty, the device will produce no sound upon receiving a push.
"android_header": "header", // optional. Android notification header.
"android_icon": "icon",
"android_custom_icon": "http://example.com/image.png", // optional. Full path URL to the image file.
"android_banner": "http://example.com/banner.png", // optional. Full path URL to the image file.
"android_badges": 5, // optional, integer. Android application icon badge number. Use "+n" or "-n" to increment/decrement the badge value by n.
"android_gcm_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds.
"android_vibration": 0, // boolean. Android force-vibration for high-priority pushes.
"android_led": "#rrggbb", // LED hex color, device will do its best approximation.
"android_priority": -1, // Sets the “importance” parameter for devices with Android 8.0 and higher, as well as the “priority” parameter for devices with Android 7.1 and lower. Establishes the interruption level of a notification channel or a particular notification. Valid values are -2, -1, 0, 1, 2.
"android_delivery_priority": "normal", // or "high", optional. Enables notification’s delivery when the device is in the power saving mode.
"android_ibc": "#RRGGBB", // icon background color on Lollipop, #RRGGBB, #AARRGGBB, "red", "black", "yellow", etc.
"android_silent": 1, // optional. 0 or 1, enable silent notificaiton (ignore sound and content).
// Amazon related
"adm_root_params": { // custom key-value object
"key": "value"
},
"adm_sound": "push.mp3",
"adm_header": "Header",
"adm_icon": "icon",
"adm_custom_icon": "http://example.com/image.png",
"adm_banner": "http://example.com/banner.png",
"adm_ttl": 3600, // optional. Time to live parameter — the maximum message lifespan in seconds.
"adm_priority": -1, // priority of the push in Amazon push drawer, valid values are -2, -1, 0, 1 and 2.
// Windows Phone related.
"wp_type": "Tile", // Windows Phone notification type. 'Tile' or 'Toast'. Raw notifications are not supported. 'Tile' is default.
"wp_background": "/Resources/Red.jpg", // tile image
"wp_backbackground": "/Resources/Green.jpg", // back tile image
"wp_backtitle": "back title", // back tile title
"wp_backcontent": "back content", // back tile content
"wp_count": 3, // optional, integer. Badge for Windows Phone notification.
// BlackBerry related
"blackberry_header": "header", // BlackBerry header, applicable to BB10 Series devices.
// Mac OS X related
"mac_badges": 3,
"mac_sound": "sound.caf",
"mac_root_params": {
"content-available": 1
},
"mac_ttl": 3600, // optional. Time to live parameter — maximum message lifespan in seconds.
// WNS related
"wns_content": { // Content (XML or raw) of notification encoded in MIME's base64 in form of Object( language1: 'content1', language2: 'content2' ) OR String
"en": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9ImF2YWlsYWJsZSIvPg==",
"de": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48YmFkZ2UgdmFsdWU9Im5ld01lc3NhZ2UiLz4="
},
"wns_type": "Badge", // 'Tile' | 'Toast' | 'Badge' | 'Raw'
"wns_tag": "myTag", // optional. Used in Tile replacement policy. An alphanumeric string of no more than 16 characters.
"wns_cache": 1, // optional. (1|0) Translates into X-WNS-Cache-Policy value.
"wns_ttl": 600, // optional. Expiration time for notification in seconds.
// Safari related
"safari_title": "Title", // obligatory. Title of the notification.
"safari_action": "Click here", // optional
"safari_url_args": [ // obligatory, but the value may be empty
"firstArgument",
"secondArgument"
],
"safari_ttl": 3600, // optional. Time to live parameter — the maximum lifespan of a message in seconds.
// Chrome related
"chrome_title": "Title", // optional. You can specify the header of the message in this parameter.
"chrome_icon": "icon_URL", // full path URL to the icon or extension resources file path
"chrome_gcm_ttl": 3600, // optional. Time to live parameter – maximum message lifespan in seconds.
"chrome_duration": 20, // optional. Changes chrome push display time. Set to 0 to display push until user interacts with it.
"chrome_image": "image_URL", // optional. URL to large image
"chrome_root_params": { // optional. Set parameters specific to messages sent to Chrome.
"key": "value"
},
"chrome_button_text1": "1", // optional
"chrome_button_url1": "button1_URL", // optional. Ignored if chrome_button_text1 is not set.
"chrome_button_text2": "2", // optional
"chrome_button_url2": "button2_url", // optional. Ignored if chrome_button_text2 is not set.
// Firefox-related
"firefox_title": "Title", // optional. You can specify message header here.
"firefox_icon": "icon_URL", // full path URL to the icon or path to the file in extension resources.
"firefox_root_params": { // optional. Set parameters specific to messages sent to Firefox.
"key": "value"
}
}
}

The basics are very simple – all filters are performed on the sets of entities.

Sets

Sets are defined as:

1. Devices subscribed to the particular app 2. Devices that match the specific tag value 3. Devices subscribed to one app of the app group

Syntax

Let’s try with some samples according to the list above.

A("XXXXX-XXXXX", ["iOS", "Android", "Blackberry", "Windows_Phone”, "OsX", "Windows", "Amazon", "Safari", "Chrome", "Firefox"])

Defines the set of devices that are subscribed to the app with the App Code “XXXXX-XXXXX”. The platform specifier is optional and, if omitted, means that the message will be sent to all platforms available for this app.

T("age", BETWEEN, [17,20])

Defines the set of the devices which have the “age” tag set to one of the values: 17, 18, 19, 20.

G("11111-11111", ["iOS","Android"])

Same as “A” but applicable to the app groups.

AT(“XXXXX-XXXXX”, “TagName”, EQ, “VALUE”)

Applicable to Application-specific Tags only.

Tags

The very important thing to understand is that tags are shared between the apps, and it presents a very powerful instrument for segmenting and filtering your target users without binding yourself to a particular app.

The tag could be one of the three different types: String, Integer, List. This defines different operators you can use for a particular tag.

String: EQ, IN, NOTIN, NOTEQ

Example: T("username", EQ, "my_username"), T("favorite_color", IN, ["red","green","blue"]).

You can use numeric values with the string tags but such values will be converted to a string.

Integer: GTE, LTE, EQ, BETWEEN, NOTIN, IN, NOTEQ

GTE – Greater than or equal to

LTE – Less than or equal to

BETWEEN – T("age", BETWEEN, [min_value,max_value]). ‘min_value’ and ‘max_value’ must be integer numbers. ‘min_value ‘must be less than ‘max_value’.

IN - T("age", IN, [value1, value2]). The tag value should be one of the following values.

NOTIN - T("age", NOTIN, [value1, value2]). The tag value should NOT be one of the following values.

NOTSET - T("username", NOTSET, "")

List: IN only.

Example: T("Category", IN, ["breaking_news","business","politics"]).

Operations

  • “+” – joins two sets

  • “*” – intersects two sets

  • “\” – subtracts one set from another All the operations are left associative. “+” and “*” have the same priority. “\” has greater priority. You can use brackets to define priorities of the calculations.

Note that “\” operation is not commutative. A("12345-12345") \ A("67890-67890") is not the same as A("67890-67890") \ A("12345-12345").

Examples

Easy:

A("00000-00000", ["iOS"]) – all iOS devices subscribed to the app 00000-00000

A("00000-00000") * T("gender", EQ, "F") – all devices subscribed to the app 00000-00000, which have the gender tag set to “female”.

A("00000-00000") * T("username", EQ, "myuser") – all devices subscribed to the app 00000-00000 which have the “myuser” username .

Hard:

( A("00000-00000") + A("11111-11111") ) \ A("12345-12345") – all devices subscribed to the app 00000-00000 OR 11111-11111, which don’t have the app 12345-12345 installed

Hardcore:

( A("00000-00000") * T("gender", EQ, "M") ) + ( A("12345-12345") * T("gender", EQ, "F") ) – Targets all men with the app 00000-00000 and all girls with the app 12345-12345

Fun:

T("gender", EQ, "F") * T("age", BETWEEN, [18, 22]) – targets college-aged girls who have any of your apps installed.

Note

You cannot use any of the following targeting-related parameters in the /createTargetedMessage request:

  • "application"

  • "applications_group"

  • "platforms"

  • "devices"

  • "filter"

  • "conditions"

All the other parameters listed in /createMessage are supported.

There is a known issue with the /createTargetedMessage method: if you don’t specify any applications in “devices_filter” section, Pushwoosh doesn’t display any applications in push details.

post
/getMsgStats

https://cp.pushwoosh.com/json/1.3/getMsgStats
Gets messages statistics.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
message
required
string
Message code obtained in /createMessage request.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"request_id": "b3337d8ec78f67280a40a5b89050c0c0"
}
}

For Private Offering subscriptions only.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"message": "xxxx-xxxxxxx-xxxxxx" // message code obtained in /createMessage request
}
}

Like every scheduled request, /getMsgStats request requires an additional /getResults request

Response body:

Field

Type

Description

request_id

string

Scheduled request Id. Please check/getResults method for more information

Scheduled (/getResults) response:

Example
{
"status_code": 200,
"status_message": "OK",
"response": {
"formatter": "minutely",
"rows": [
{
"datetime": "2015-09-30 12:54:00",
"action": "send",
"count": "3",
},
{
"datetime": "2015-09-30 12:54:00",
"action": "open",
"count": "2",
},
{
"datetime": "2015-09-30 12:54:00",
"action": "send",
"count": "59",
},
.................
]
}
}

post
/getMsgPlatformsStats

https://cp.pushwoosh.com/json/1.3/getMsgPlatformsStats
Gets messages statistics for one or several platforms.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
message
required
string
Message code obtained in /createMessage request.
platforms
required
array
List of platform types, array of integers. See /registerDevice for the complete list.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"request_id": "287870092dc23175af5dc48ba1dc7f3c"
}
}

For Private Offering subscriptions only.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"message": "xxxx-xxxxxxx-xxxxxx", // message code or message ID
"platforms":[1,2,3,4,5] // list of platform types. Please see /registerDevice for the complete list of platform types
}
}

As every scheduled request, /getMsgPlatformsStats request requires an additional /getResults request.

Response body:

Field

Type

Description

request_id

string

Scheduled request Id. Please check/getResults method for more information

Scheduled (/getResults) response:

Example
{
"status_code": 200,
"status_message": "OK",
"response": {
"formatter": "minutely",
"rows": [
{
"datetime": "2015-09-30 12:54:00",
"action": "send",
"count": "3",
},
{
"datetime": "2015-09-30 12:54:00",
"action": "open",
"count": "2",
},
{
"datetime": "2015-09-30 12:54:00",
"action": "send",
"count": "59",
},
.................
]
}
}

post
/createPreset

https://cp.pushwoosh.com/json/1.3/createPreset
Creates a new preset.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
name
required
string
Preset name.
applicationCode
required
string
Pushwoosh application code.
campaignCode
optional
string
Code of a campaign to which you want to assign this preset.
content
required
object
Message content parameters.
content.message
required
string
String or array. Messages content. In case it's a string, the "Default" language will be used.
content.action
optional
object
Custom action parameters. See the example below.
content.userData
optional
array
Custom user data. Will be passed as "u" parameter in the payload (converted to JSON string).
content.platforms
optional
array
Specific content for different platforms. See the example below.
scheduling.sendRate
optional
integer
Throttling. Valid values are from 100 to 1000 pushes/second.
segmentation
optional
object
Segmentation parameters
segmentation.filter
optional
string
Filter name
segmentation.platforms
optional
array
Array of integers. The list of platforms ids. 1 - iOS, 2 - BB, 3 - Android, 5 - Windows Phone, 7 - OS X, 8 - Windows 8, 9 - Amazon, 10 - Safari, 11 - Chrome, 12 - Firefox. Ignored if "devices"<10
200: OK
{
"status_code":200,
"status_message":"OK"
}
Example
{
"request": {
"auth": "yxoPUlwqm…………pIyEX4H", // required, string. API access token from Pushwoosh Control Panel.
"name": "PRESET_NAME", // required, string.
"applicationCode": "XXXXX-XXXXX", // required, string. Pushwoosh application code.
"applicationGroupCode": "AAAAA-BBBBB", // optional, string. Can be used instead of "applicationCode".
"campaignCode": "CCCCC-DDDDD", // optional, string. Campaign code.
"content": { // required, array. Contains message data.
"message": { // required, string or array. Message content. In case it's a string, the default language will be used.
"en": "English message", // Message content localized for different languages. Only ISO 639-1:2002 for language codes.
"fr": "French message"
},
"action": { // optional, array. Action to be performed once a user opens a message.
"type": "url", // string. Type of action. Available types: `url`, `deepLink`, `richMedia`, `openApp`(default).
"options": { // array. Options for action types. Required for all action types except for `openApp`.
"url": "http://example.com", // required for `url` action type, string. Will be shortened if shortener is defined.
"shortener": 2, // optional, integer. Available values: 0 — do not minimize, 2 — bit.ly. If no shortener is specified, bit.ly shortener will be used by default.
"richMediaCode": "BBBBB-AAAAA", // required for `richMedia` action type, string. Rich Media code from Pushwoosh Control Panel.
"id": 123, // required for "deepLink" action type, integer. Deep Link ID.
"params": { // custom parameters, required for "deepLink" action type, array.
"param1": "value1",
"param2": "value2"
}
}
},
"userData": { // optional, array. Custom user data. Will be passed as "u" parameter in the payload (converted to JSON string).
"CustomData": "value"
},
"platforms": {// optional, array. Specific content for different platforms.
// See the platform-specific examples in /createMessage request.
}
},
"scheduling": { // optional, array. Scheduling options.
"sendRate": 1000 // optional, integer. Throttling. Valid values are from 100 to 1000 pushes/second.
},
"segmentation": { // required, array. Segmentation options.
"filter": "FILTER NAME", // optional, string. Filter name from your Pushwoosh Control Panel.
"platforms": [11,3] // required, array. The list of platforms IDs: 1 — iOS; 2 — BB; 3 — Android; 5 — Windows Phone; 7 — OS X; 8 — Windows 8; 9 — Amazon; 10 — Safari; 11 — Chrome; 12 — Firefox; ignored if "devices" < 10
}
}
}

For platform-specific parameters, please refer to /createMessage.

post
/getPreset

https://cp.pushwoosh.com/json/1.3/getPreset
Retrieves the parameters of the specific push preset.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
preset_code
required
string
Push preset code to retrieve information for.
200: OK
{
"status_code":200,
"status_message":"OK",
"response":{
"preset":{
"code":"XXXXX-XXXXX",
"name":"Full preset",
"page_id":26,
"url":null,
"content":{
"en":"Some eng message",
"ru":"\u041a\u0430\u043a\u043e\u0439-\u0442\u043e \u0442\u0435\u043a\u0441\u0442"
},
"properties":{
"ignore_user_timezone":1,
"ios_badges":"5",
"ios_sound":"default",
"ios_ttl":"43200",
"android_sound":"Sound1.wav",
"android_custom_icon":"icon.png",
"android_header":"android_header",
"android_gcm_ttl":"43200",
"wns_type":"toast",
"wns_content":{
"template":"ToastImageAndText02",
"lang-en":{
"headlinetext":"Title",
"bodytext":"super text"
},
"languages":["en", "zh", "it", "sv", "de", "fr", "ru", "pt", "nl", "es"],
"lang-zh":{
"headlinetext":"",
"bodytext":""
},
"lang-it":{
"headlinetext":"",
"bodytext":""
},
"lang-sv":{
"headlinetext":"",
"bodytext":""
},
"lang-de":{
"headlinetext":"",
"bodytext":""
},
"lang-fr":{
"headlinetext":"",
"bodytext":""
},
"lang-ru":{
"headlinetext":"",
"bodytext":""
},
"lang-pt":{
"headlinetext":"",
"bodytext":""
},
"lang-nl":{
"headlinetext":"",
"bodytext":""
},
"lang-es":{
"headlinetext":"",
"bodytext":""
},
"imagesource":"http:\/\/image.com\/jpg"
},
"blackberry_header":"Some Header",
"adm_sound":"song",
"adm_custom_icon":"i5.bmp",
"adm_header":"Amazon Header",
"adm_ttl":"7200",
"wp_type":"Tile",
"wp_background":"i1.png",
"wp_count":5,
"wp_backbackground":"i2.png",
"wp_backtitle":"back title",
"wp_backcontent":"back content",
"safari_title":"Safari title",
"safari_action":"OK",
"safari_url_args":["hello.com", ""],
"safari_ttl":"43200",
"userdata":"{\"custom\":\"data\"}",
"created_via":"CP",
"user_id":2,
"filter_id":"1"
},
"platforms":[1,3,2,5,9,4,7,8,10]
}
}
}

For Private Offering subscriptions only.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"preset_code": "AAAAA-BBBBB" // push preset code to retrieve information for
}
}

post
/getPushHistory

https://cp.pushwoosh.com/json/1.3/getPushHistory
Gets push history via the API.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
source
optional
string
Push history source. Can be null or: "CP", "API", "GeoZone", "Beacon", "RSS", "AutoPush", "Twitter", "A/B Test".
searchBy
optional
string
Possible values to search by. Can be null or: "notificationID", "notificationCode", "applicationCode", "campaignCode".
value
optional
string
Search value set according to the "searchBy" field.
lastNotificationID
optional
string
Used for pagination. Last messageId from the previous /getPushHistory call. See details below.
200: OK
{
"status_code":200,
"status_message":"OK",
"response": {
"rows": {
"id":91133,
"createDate":"2015-11-27 07:01:31",
"sendDate":"2015-11-27 07:01:31",
"content":{"en":"test"},
"url":null,
"filter":"#000Integer(\u226045)",
"richPageId":null,
"geozone":"{\"lat\":55.002825809793,\"lng\":82.905578613281,\"range\":1000}"
}
}
}

For Private Offering subscriptions only.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"source": null, // optional. Possible values are null, "CP", "API","GeoZone", "Beacon", "RSS", "AutoPush","Twitter", "A/B Test"
"searchBy": "applicationCode", // optional. Possible values are "", "notificationID", "notificationCode", "applicationCode", "campaignCode"
"value": "C8717-703F2", // optional
"lastNotificationID": 0 // optional
}
}

This method will return 1000 messages from the account sorted by message Id. To get the second page, specify the last message Id of previous response in the lastNotificationId parameter.

post
/getResults

https://cp.pushwoosh.com/json/1.3/getResults
Retrieves the result of a scheduled request.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
request_id
required
string
Request ID returned by a scheduled method.
200: OK
{
"status_code": 200,
"status_message": "OK",
"response": {
"applications": {
"formatter": "minutely",
"rows": []
},
"devices": {
"formatter": "minutely",
"rows": []
},
"messages": {
"formatter": "minutely",
"rows": []
}
}
}

For Private Offering subscriptions only.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"request_id": "REQUEST_ID" // request ID returned by the scheduled method
}
}

This method is used with every scheduled request to receive a response.

post
/cancelMessage

https://cp.pushwoosh.com/json/1.3/cancelMessage
Deletes a scheduled message.
Request
Response
Body Parameters
auth
required
string
API access token from Pushwoosh Control Panel.
message
required
string
The message code obtained in /createMessage response.
200: OK
{
"status_code":200,
"status_message":"OK"
}

The method is only allowed for messages that are in the status of pending, waiting or processing.

Example
{
"request":{
"auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
"message": "xxxx-xxxxxxx-xxxxxx" // the message code obtained in /createMessage response
}
}

Status codes:

HTTP Status code

status_code

Description

200

200

Message successfully canceled

200

210

Argument error. See status_message for more info.

400

N/A

Malformed request string

500

500

Internal error