/createMessage parameters

Here you'll find the descriptions of the /createMessage API parameters. Required parameters provide successful posting a /createMessage API request and sending a broadcast push notification at the specified time. Optional parameters allow you to customize push notification's properties deeply.

Required parameters

Required parameters are obligatory to use in /createMessage requests. Otherwise, the request won't be submitted.

application

Unique code of an app created in your Pushwoosh account. App code can be found in Control Panel or in response to a /createApplication request. The app code is a hyphen-separated set of 10 characters (both letters and digits).

To obtain an app code, go to Control Panel, and open the Applications section. Here, you’ll see the list of your apps with app codes below.

When creating an app via the API, you’ll get an app code in response to your /createApplication request.

To obtain a code of a previously created app via the API, call /getApplications. In response to the /getApplications request, you'll receive the list of all apps created in your Pushwoosh account with their names and codes.

auth

API access token from Pushwoosh Control Panel. Go to API Access section and copy a token you’d like to use or generate a new one.

When generating an access token, specify its permissions. Check the checkboxes for those types of activities you're going to use the API token with. You can create app-specific API tokens by checking the Applications checkboxes. To send emails via the API, check the Email API checkbox.

content

A string or an object to define a message's content. The "content" parameter submitted with a string type value will send the same message for all recipients.

String
"content": "Hello world!",

JSON objects are used for specifying content using Dynamic Content, for example, for multi-language messages.

Object
"content": {
"en": "Hello!",
"es": "¡Hola!",
"de": "Hallo!"
},

notifications

A JSON array of push properties. Must include at least the "content" and the "send_date" required params.

Optional parameters to use within the "notifications" array:

send_date

Date and time on which the message is sent. Could be any date and time formatted as YYYY-MM-DD HH:mm or 'now'. If set to 'now', the message will be sent immediately after submitting the request.

Optional parameters

applications_group

A code of an app group from Pushwoosh Control Panel. Can be used instead of the "application" parameter to target users of all apps in the group. To obtain an Application Group code, go to Control Panel and open the Application Groups section. Here, you’ll see the list of your app groups with their codes.

campaign

A code of a Campaign. To obtain a Campaign code, select an app in Pushwoosh Control Panel, go to Campaigns section, and press the Edit button for a Campaign you’re going to use. A Campaign code is a hyphen-separated set of 10 characters (both letters and digits).

To obtain a list of Campaigns with their codes, call /getCampaigns. In response to the /getCampaigns request, you'll receive the list of all Campaigns created for a particular app in your Pushwoosh account, with their codes, names, and descriptions.

capping_days

Period to be applied for frequency capping, in days (max 30 days). See Frequency Capping guide for details.

capping_count

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. See Frequency Capping guide for details.

conditions

Conditions are arrays like [tagName, operator, operand] used for sending targeted messages based on Tags and their values, where:

  • tagName — the name of a tag to apply,

  • operator — a value comparison operator ("EQ" | "IN" | "NOTEQ" | "NOTIN" | "LTE" | "GTE" | "BETWEEN" | "NOTSET" | "ANY"),

  • operand — Tag values of any of the following types: string | integer | array | date | boolean | list

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 is 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 is 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 is 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 a push notification to Portuguese-speaking subscribers in Brazil, you will need to specify the following condition: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

conditions_operator

Logical operator for conditions arrays. Possible values: AND | OR. AND is default.

If the operator applied is AND (when no operator is specified, or the 'conditions_operator' param has the 'AND' value), devices simultaneously complying with all the conditions will receive the push notification.

If the operator is OR, devices that comply with any of the specified conditions will receive the message.

data

JSON string or JSON object used to pass any custom data in the push payload; is passed as "u" parameter in the payload (converted to JSON string).

devices

An array of push tokens or hwids to send targeted push notifications. If set, the message will only be sent to the devices on the list.

dynamic_content

Placeholders for Dynamic Content to be used instead of device Tag values. The example below will send the "Hello, John!" message to every user you target. If not set, the Dynamic Content values are taken from the device Tags.

"content": "Hello, {firstname|CapitalizeFirst}!",
"dynamic_content_placeholders": {
"firstname": "John",
"lastname": "Doe"
},

filter

A name of a Filter exactly as it’s created in Pushwoosh Control Panel or via a /createFilter API request. Go to Filters section of your Pushwoosh Control Panel and check the list of filters created.

To get Filters list via the API, call the /listFilters API method. In response to the /listFilters request, you'll receive the list of all Filters created in your Pushwoosh account, with Filters' names, conditions, and expiration dates.

geozone

The latitude, longitude, and range of a Geozone you're going to use in your API request.

To get the parameters of the existing Geozone, go to Pushwoosh Control Panel, open the Geozones section, and press the Edit button of a Geozone you're going to apply. Here, you'll see the Geozone's settings, including its latitude, longitude, and range.

ignore_user_timezone

If set to 'true', sends the message at the time and date specified in the "send_date" parameter according to UTC-0.

If set to 'false', users will receive the message at the specified local time according to their device's settings.

inbox_date

The date until which the message should be kept in users' Inbox. If not specified, the message will be removed from Inbox on the next day after the sending date.

To save the message to Inbox, use at least one of the 'inbox' parameters: "inbox_date" or "inbox_image".

inbox_image

The URL of the custom image to be shown near the message in Inbox.

To save the message to Inbox, use at least one of the 'inbox' parameters: "inbox_date" or "inbox_image".

The URL to be opened once a user opens a push notification.

Shortener to minimize the URL submitted in the "link" parameter. Please note that push notification payload size is limited, so consider creating short URLs not to exceed the limit. Available values: 0 — do not minimize, 2 — bitly. Default = 2. Google URL shortener is disabled since March 30, 2019.

platforms

An array of platforms' codes to send the message to specific platforms only. List of platforms available: 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

A code of a Preset created in Pushwoosh Control Panel or via API. To obtain a preset code, go to the Presets section, expand the one you are going to use, and copy the Preset Code from preset's details.

rich_media

A code of a Rich Media page you're going to attach to your message. To obtain a code, go to Rich Media section of Pushwoosh Control Panel, press Edit button of a Rich Media page you are going to use, and copy the code from the URL bar of your browser. The code is a hyphen-separated set of 10 characters (both letters and digits).

send_rate

Throttling to restrain the push sending speed. Valid values are from 100 to 1000 pushes/second.

timezone

Timezone to be taken into account when the message is sent on a particular date and time. If set, the device's timezone is ignored. If ignored, the message is sent in UTC-0. See http://php.net/manual/timezones.php for supported timezones.

template_bindings

Template placeholders to use in your content template. See the Template Engine guide for details.

transactionId

Unique message identifier to prevent duplicating messages in case of network problems. You can assign any ID to a message created via the /createMessage or /createTargetedMessage request. Stored on the side of Pushwoosh for one day.

use_template

The boolean parameter to enable content templating. See the Template Engine guide for details.

users

An array of userIds. User ID is a unique user identifier set by a /registerUser, /registerDevice, or /registerEmail API request.