Creates a new targeted push notification
Creates a new targeted push notification.
Platform-specific parameters:
{
"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"
}
}
}
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.
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 guide 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.