The API create method for campaigns supports a wide range of parameters to add content, segmentation, location, scheduling and message expiry options. The following sections describe these.

Content

Message content


push_title	string	The title of your push message.
push_text	string	The text of your push message.
push_icon	string	The URL of an image to be used as push message icon.
push_picture_type	string	Indicates the source of the image. Value must be set to `url`, which is the only available option when creating the campaign via API.
push_picture	string	The URL of an image to be used in push, e.g. `https://pathtoyourhostedimage.com/large/gold-coast-coffee30665.jpg`. On Android, used for Android standard big picture element, on iOS used to add the default "picture" payload for use in rich media.
messages	json	Used to set different content for different messages (for example ios and android message, or web push message and inbox message). It should be an object where the key is a message type and the value is message content. 1 - Push message on iOS 2 - Push message on Android 3 - Push message on Web 6 - Inbox message 7 - email message 8 - webhook message 9 - SMS message

Examples

Android send now broadcast campaign:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken":"YOUR_APP_TOKEN",
    "title": "First Android Test",
    "android_push": 1,
    "encryption": "0",
    "broadcast": 1,
    "push_title": "First Android Test",
    "push_text": "Testing Android Ping!",
    "push_picture_type": "url",
                "push_picture": "https://example.com/image.png"
  }'

iOS send now broadcast campaign:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOUR_APPTOKEN",
    "title": "First iOS Test",
    "ios_push": 1,
    "ios_push_sandbox": 1,
    "broadcast": 1,
    "push_text": "Testing iOS Ping!"
  }'

A web push campaign targeting Chrome, Firefox and Opera with an inbox message:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
	  "apptoken": "YOUR_APPTOKEN", 
  	"title": "El Clasico", 
    "web_push": 1, 
    "web_push_chrome": 1, 
    "web_push_firefox": 1, 
    "inbox": 1, 
    "messages": {
      "3": {
        "push_title": "El Clasico", 
        "push_text": "1-0! Messi scores.", 
        "url": "https://mywesbite.com/destination.html?from=push"
      },
      "6": {
        "inbox_type": "1", 
        "push_title": "El Clasico", 
        "push_text": "60\" - Messi scores. 1-0", 
        "url": "https://mywesbite.com/destination.html?from=inbox"
      }
    }
  }'

A webhook campaign using an SMS provider platform:

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOUR_APP_TOKEN",
    "title": "webhookSmsExample",
    "webhook": 1,
    "broadcast": 1,
    "messages": {
      "8": {
        "webhook": {
          "url": "https://rest.smsprovider.com/sms/json",
          "get_params": [
            {
              "key": "text",
              "value": "your activation code is \"4321\""
            },
            {
              "key": "from",
              "value": "Xtremepush"
            },
            {
              "key": "to",
              "value": "12345"
            },
            {
              "key": "api_secret",
              "value": "SMSPROVIDER_SECRET"
            },
            {
              "key": "api_key",
              "value": "API_KEY"
            }
          ],
          "request_body_type": "raw",
          "request_body_data": {
            "raw": "",
            "post": "",
            "json": ""
          },
          "request_headers":""
        }
      }
    }
  }'

📘
Broadcast
The broadcast parameter is shown in the examples above as "broadcast" : 1. This is used to send your message to the whole user base. The default "broadcast" : 0 expects a segment of users to be applied to the campaign. See below for more segmentation params.

Linked Content


url	string	The URL that users will be taken to when they open the message.
url_browser	boolean	Boolean, 0 = "open url in web view" or 1 = "open url in browser".
page	string	Custom HTML code for page that will users will be brought to when they open the message..
payload_add	array of strings	Used to add payload. Should be an array of objects with two elements, one named "key" and one named "value".

Multi-language content

If you need a campaign with multiple language content, this is possible. Content will, of course, vary with language. For example, a url for when the user clicks on the message can be shared or can link to different places for different languages. Examples of this are shown below the params table.


languages_multi	boolean	Enable multi language content.
languages_list	array of strings	List of languages using the ISO 639-1 two letter language value.
languages_default	string	A fallback language for users who don't match any of the listed languages.
push_text_languages	array of strings	Translations for the push text, where the key is a language code and the value is a translation. This will override the push_text param when multi-language is enabled.
push_title_languages	array of strings	Translations for the push title, where the key is a language code and the value is a translation. This will override push_title param when multi-language is enabled.
url_languages	array of strings	Language specific URLs, where the key is a language code and the value is a URL. This will override the url param when multi-language is enabled.

Examples

Post data using the same URL for different languages

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{ 
    "apptoken": "APP_TOKEN",
    "title": "Inbox Multilanguage with same URL",
    "inbox": 1,
    "languages_multi": 1,
    "languages_list": ["en", "ru"],
    "languages_default": "en",
    "messages": { 
      "6": { 
        "push_title_languages": {
          "en": "Test",
          "ru": "Тест"
        },
        "push_text_languages": {
          "en": "Hello",
          "ru": "Привет"
        },
        "url": "https://website-local.xtremepush.com?lang=common"
      }
    }
  }'

Post data for using a different URL per language

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{ 
    "apptoken": "APP_TOKEN",
    "title": "Inbox Multilanguage with diff URL",
    "inbox": 1,
    "languages_multi": 1,
    "languages_list": ["en", "ru"],
    "languages_default": "en",
    "messages": {
      "6": {
        "push_title_languages": {
          "en": "Test",
          "ru": "Тест"
        },
        "push_text_languages": {
          "en": "Hello",
          "ru": "Привет"
        },
        "url_languages": {
          "en": "https://website-local.xtremepush.com?lang=en",
          "ru": "https://website-local.xtremepush.com?lang=ru"
        }
      }
    }
  }'

Email content

The email channel is turned on with "email": 1 , the email type 7 is added to the messages object with params for the email content.


email_type	int32	Set to 1 to indicate the email comes from API.
email_subject	string	Subject text of email.
email_html	string	The html of your email.
email_text	string	The text for the plain text version of your email.
email_unsubscribe	boolean	To use the unsubscribe header or not.
email_address_id	int32	The id of the verified from address you want to use.
email_template	int32	Set this to 1.

Example

The email address id can be found in the table showing your list of verified emails. These can be found on the platform by going to Account > Email Addresses.

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOURAPPTOKEN",
    "title": "Email Example via API", 
    "email": 1,
    "broadcast": 1,
    "messages": {
      "7": { 
        "email_address_id": xxx,
        "email_subject": "Hi {{first_name}}, check out our sample API email test",
        "email_unsubscribe": 0,
        "email_text": "[Image]\n\nEditor 2.0 now available\n\nThe New Drag and Drop Editor is Here!\n\nOur amazing email editor with built in responsive design has now become even better, giving you full control over rows and columns\n\n[Image]",
        "email_type":1, 
        "email_template": 1,
        "email_html":"YOUR FULLY RESPONSIVE EMAIL HTML"
      }
    }
  }'

SMS Content

The sms channel is turned on with "sms":1 , the SMS type 9 is added to the messages object with params for the sms content.


sms	array of strings	Array containing the from and text parameters.
from	string	The from header used to identify your brand.
text	string	The body text of the sms message.

Example

In this example "broadcast":1 is used to target your entire available user base, conditions that target a subsection of your audience, and scheduling and other options can be added as described in the general overview of campaign methods. In this example a personalisation tag has been added in the SMS text to pull in the users' first names.

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOURAPPTOKEN",
    "title": "SMS Example via API", 
    "sms": 1,
    "broadcast": 1,
    "messages": { 
      "9": {
        "sms": {
          "from": "xtremepush",
          "text": "{{first_name}}, check out our SMS API test"
        }
      }
    }
  }'

Segmentation

Segmentation broadcast param must be applied to each campaign, even if you are sending to the entire user base.


broadcast	boolean	0 - send push for targeted users using conditions (default value) 1 - send push to everybody
conditions	array of strings	Filter devices by conditions. See segmentation methods to understand how to create conditions. The following params are alternative ways to create conditions.
segments	array of integers	Array of segment IDs used to associate a list of previously created segments.
idArray	array of integers	Array of Xtremepush device IDs that message is going to be sent to.
tokenArray	array of integers	Array of device tokens that message is going to be sent to.
deviceIdArray	array of integers	Array of device UUIDs that message is going to be sent to.
externalIdArray	array of strings	Array of device external IDs that message is going to be sent to.

Examples

An iOS send now campaign with a payload, and an attribute is equal to on condition attached.

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "YOUR_APPTOKEN",
    "title": "El Clasico",
    "ios_push": 1,
    "ios_push_sandbox": 1,
    "push_text": "1-0! Messi scores.",
    "payload_add": [
      {
        "key": "score",
        "value": "1-0"
      }
    ],
    "conditions": {
      "operator": "AND",
      "0": {
        "operator": "AND",
        "0": [
          "tags_attribute",
          "=",
          "live_scores",
          [
            "value",
            "=",
            "on"
          ]
        ]
      }
    }
  }'

Geo / iBeacon campaigns


locations	array if integers	Array of location IDs used to associate a list of previously created locations (see location API methods below) e.g. "locations": [1,2,3]
location_trigger	int32	1 - trigger on entering location 2 - trigger on exiting location 3 - trigger after dwell time
location_dwell_time	int32	Value from 1 to 30 - dwell time in minutes (required if trigger is dwell time).
location_limit_per_user	int32	User notification limit per {location_limit_per_user_period} (1 by default).
location_limit_per_user_period	string	Value of "campaign" or "day" - period used in {location_limit_per_user} (day by default).
location_limit_per_location	int32	User notification limit per location per {location_limit_per_user_period} (1 by default).
location_limit_per_location_period	string	Value of "campaign" or "day" - period used in {location_limit_per_location} (day by default).
location_limit_nth_hit	int32	Number of events needed to fire trigger (0 by default).
location_limit_nth_hit_period	string	Value of "campaign" or "day" - period used in {location_limit_nth_hit} (day by default).

Scheduled campaigns


send_type	int32	0 - Send Now 1 - Once in the Future 2 - Recurring/Triggered
send_date	string	Date a once off scheduled campaign should be sent (format: YYYY-MM-DD).
send_time	string	A one off or recurring scheduled campaign should be sent (format: HH:MM).
start_date	string	Start Date for a recurring/triggered campaign (format: YYYY-MM-DD) (current date by default).
end_date	string	The date the campaign should be stopped (format: YYYY-MM-DD) (optional campaign must be manually stopped if not set).
start_time	string	The time of day a triggered campaign should start (format: HH:MM) (00:00 by default) - campaign can be triggered between the start and end time.
end_time	string	The time of the day a triggered campaign should end (format: HH:MM) (23:59 by default).
send_days	array of integers	An array of day numbers on which a recurring/triggered campaign should be running (all days are specified by default).
timezone	string	The timezone used for start_date, end_date, start_time, end_time attributes. If the timezone is not specified then the "users timezone", set in the application is used.

📘
Schedule setting
A campaign to be sent once in the future will have schedule details like:
"send_type": 1, "send_date": "2015-04-06", "send_time": "09:00"
A recurring campaign to be sent once a day at certain time will have schedule details like:
"send_type": 2, "send_days": [1, 2, 3, 4, 5, 6, 7]}, "start_date": "2015-04-06", "end_date": "2015-04-12”, "send_time": "09:00"
A triggered campaign (Geo / iBeacons, Event, Api) will have schedule details like:
"send_type": 2, "send_days": [1, 2, 3, 4, 5, 6, 7]}, "start_date": "2015-04-06", "end_date": "2015-04-12”, "start_time": "00:01", “end_time": "23:59"
Note: If you are updating your API integration and the syntax looks different from above then you are possibly using an older version of the create method with different syntax. We recommend that you use the new syntax. However, if you have already completed your integration and you still need a copy of this documentation, please contact us.

Message Timing

Push Expiry Options


retry_for	int32	The length of time to retry message delivery. 4 weeks by default.
retry_for_period	string	A period of time to retry message delivery, can be seconds / minutes / hours / days / weeks.
retry_until	int32	Unix timestamp. The message delivery will not be retried after this timestamp.

Inbox Persist Options


persist_for	int32	The message will be removed from the user inbox after this length of time. Not set by default.
persist_for_period	string	A period of time for the message to remain in the user inbox once delivered.
persist_until	int32	Unix timestamp. The message will be removed from the user inbox at this timestamp.

Webhooks for deliveries and responses

For API-based campaigns you can post back delivery and click-through info to your own or a collaborator's endpoints for tracking purposes if necessary. This will work for both the template and trigger, and create and send patterns.

🚧
Delivery notifications will not function as expected for Android Push, iOS Push or Safari Web-Push campaigns. It is not recommended to rely on the post-backs for these types of messages due to the nature of the channel.
Deliveries can be tracked as expected for Chrome, Opera and Firefox web push.

Two optional parameters can be added to both API requests:

Parameter	Description
webhook_delivery	The endpoint to send delivery data
webhook_open	The endpoint to send open/click response data

Template and trigger

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/execute/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "APPTOKEN",
    ....,
    "webhook_delivery": "https://example.com/webhook/campaign-delivered",
    "webhook_open": "https://example.com/webhook/campaign-opened",
  }'

👍
When using the Template and Trigger pattern to do one-to-one messaging, you can potentially construct unique post-back URLs for each execution if that suits your tracking use-case, for example:
"webhook_open": "https://example.com/webhook/unique-identifier"

Create and send

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/create/campaign \
  --header 'content-type: application/json' \
  --data '{
    "apptoken": "APPTOKEN",
    ....,
    "webhook_delivery": "https://example.com/webhook/campaign-delivered",
    "webhook_open": "https://example.com/webhook/campaign-opened",
  }'

Webhook Request

When a message, such as an email, is successfully delivered there will be a post-back to the webhook_delivery endpoint and if it is opened/clicked then there will be a post-back to the webhook_open endpoint. Data will take the following format:

{
    "time": TIMESTAMP_OF_EVENT,
    "device": {"id": DEVICE_ID},
    "profile": {"id": PROFILE_ID, "user_id": CUSTOMER_ID}   
    "send": {"id": SEND_ID},
    "campaign": {"id": CAMPAIGN_ID}
}