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_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 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 Classico", 
    "web_push": 1, 
    "web_push_chrome": 1, 
    "web_push_firefox": 1, 
    "inbox": 1, 
    "messages": {
      "3": {
        "push_title": "El Classico", 
        "push_text": "1-0! Messi scores.", 
        "url": "https://mywesbite.com/destination.html?from=push"
      },
      "6": {
        "inbox_type": "1", 
        "push_title": "El Classico", 
        "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": "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.

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 Classico",
    "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 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}
}