User GuideDeveloper GuideAPI Reference
Xtremepush.com

Campaign model properties

This page describes the fields for the campaign create API endpoint

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_titlestringThe title of your push message.
push_textstringThe text of your push message.
push_iconstringThe URL of an image to be used as push message icon.
push_picture_typestringIndicates the source of the image. Value must be set to url, which is the only available option when creating the campaign via API.
push_picturestringThe 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.
messagesjsonUsed 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

urlstringThe URL that users will be taken to when they open the message.
url_browserbooleanBoolean, 0 = "open url in web view" or 1 = "open url in browser".
pagestringCustom HTML code for page that will users will be brought to when they open the message..
payload_addarray of stringsUsed 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_multibooleanEnable multi language content.
languages_listarray of stringsList of languages using the ISO 639-1 two letter language value.
languages_defaultstringA fallback language for users who don't match any of the listed languages.
push_text_languagesarray of stringsTranslations 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_languagesarray of stringsTranslations 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_languagesarray of stringsLanguage 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_typeint32Set to 1 to indicate the email comes from API.
email_subjectstringSubject text of email.
email_htmlstringThe html of your email.
email_textstringThe text for the plain text version of your email.
email_unsubscribebooleanTo use the unsubscribe header or not.
email_address_idint32The id of the verified from address you want to use.
email_templateint32Set 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.

smsarray of stringsArray containing the from and text parameters.
fromstringThe from header used to identify your brand.
textstringThe 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": "Email 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.

broadcastboolean0 - send push for targeted users using conditions (default value)
1 - send push to everybody
conditionsarray of stringsFilter devices by conditions. See segmentation methods to understand how to create conditions.
The following params are alternative ways to create conditions.
segmentsarray of integersArray of segment IDs used to associate a list of previously created segments.
idArrayarray of integersArray of Xtremepush device IDs that message is going to be sent to.
tokenArrayarray of integersArray of device tokens that message is going to be sent to.
deviceIdArrayarray of integersArray of device UUIDs that message is going to be sent to.
externalIdArrayarray of stringsArray 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

locationsarray if integersArray of location IDs used to associate a list of previously created locations (see location API methods below) e.g. "locations": [1,2,3]
location_triggerint321 - trigger on entering location
2 - trigger on exiting location
3 - trigger after dwell time
location_dwell_timeint32Value from 1 to 30 - dwell time in minutes (required if trigger is dwell time).
location_limit_per_userint32User notification limit per {location_limit_per_user_period} (1 by default).
location_limit_per_user_periodstringValue of "campaign" or "day" - period used in {location_limit_per_user} (day by default).
location_limit_per_locationint32User notification limit per location per {location_limit_per_user_period} (1 by default).
location_limit_per_location_periodstringValue of "campaign" or "day" - period used in {location_limit_per_location} (day by default).
location_limit_nth_hitint32Number of events needed to fire trigger (0 by default).
location_limit_nth_hit_periodstringValue of "campaign" or "day" - period used in {location_limit_nth_hit} (day by default).

Scheduled campaigns

send_typeint320 - Send Now
1 - Once in the Future
2 - Recurring/Triggered
send_datestringDate a once off scheduled campaign should be sent (format: YYYY-MM-DD).
send_timestringA one off or recurring scheduled campaign should be sent (format: HH:MM).
start_datestringStart Date for a recurring/triggered campaign (format: YYYY-MM-DD) (current date by default).
end_datestringThe date the campaign should be stopped (format: YYYY-MM-DD) (optional campaign must be manually stopped if not set).
start_timestringThe 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_timestringThe time of the day a triggered campaign should end (format: HH:MM) (23:59 by default).
send_daysarray of integersAn array of day numbers on which a recurring/triggered campaign should be running (all days are specified by default).
timezonestringThe 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_forint32The length of time to retry message delivery. 4 weeks by default.
retry_for_periodstringA period of time to retry message delivery, can be seconds / minutes / hours / days / weeks.
retry_untilint32Unix timestamp. The message delivery will not be retried after this timestamp.

Inbox Persist Options

persist_forint32The message will be removed from the user inbox after this length of time. Not set by default.
persist_for_periodstringA period of time for the message to remain in the user inbox once delivered.
persist_untilint32Unix 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:

ParameterDescription
webhook_deliveryThe endpoint to send delivery data
webhook_openThe 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}
}