Campaign Methods

The five campaign methods are used to create, send, update or get info about messaging campaigns. Available Methods are:

• Create: Create an automated or immediate campaign 
• Send: Send an immediate campaign
• Update: Update an existing campaign
• Remove: Remove a campaign element like an inbox message
• List: Query existing campaigns and get a list of results
• Info: Get info on a single campaign

 

Create

Used to create an automated campaign or create a campaign to be dispatched immediately with the send API method. 

URL

api/external/create/campaign

Parameters

Parameter	Description
apptoken	Your App token
title	The title of your campaign
trigger	0 - Scheduled campaign (default value)
	1 - Geo / iBeacon triggered campaign
	2 - Event triggered campaign
	3 - Api triggered campaign
Channels
email	Boolean 0/1 - enable email message
sms	Boolean 0/1 - enable sms message
android_push	Boolean 0/1 - enable push message on Android
ios_push	Boolean 0/1 - enable push message on iOS
ios_push_production	Boolean 0/1 - enable push message for iOS production builds
ios_push_sandbox	Boolean 0/1 - enable push message for iOS dev builds
web_push	Boolean 0/1 - enable push message on Web
web_push_chrome	Boolean 0/1 - enable push message for Chrome
web_push_firefox	Boolean 0/1 - enable push message for Firefox
web_push_safari	Boolean 0/1 - enable push message for Safari
inbox	Boolean 0/1 - enable inbox message
webhook	Boolean 0/1 - enable webhook message
	All the channels above are turned off by default (set to 0)
Message Content	some samples for push below
push_title	The title of your push message
push_text	The text of your push message
push_icon	URL of image to be used as push message icon
push_picture	URL of image to be used in push - 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	Can be 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 array 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
	Usage Examples: Examples of usage elsewhere in docs for email, sms, webhooks
Linked Content
url	URL that users will be brought to when they open the message
url_browser	Boolean, 0 = "open url in web view" or 1 = "open url in browser"
page	Custom HTML code for page that will users will be brought to when they open the message.
payload_add	Used to add payload (key,value) pairs
Multi-Language Content
languages_multi	Boolean 0/1 - enable multi language content
languages_list	Array - list of languages using two letters code (ISO 639-1)
languages_default	String - fallback language for users who don't speak any of the listed languages
push_text_languages	Array - translations for the push text. Where the key is a language code and the value is a translation. This will override push_text option when multi-language is enabled.
push_title_languages	Array - translations for the push title. Where the key is a language code and the value is a translation. This will override push_title option when multi-language is enabled.
url_languages	Array - language specific URLs. Where the key is a language code and the value is a URL. This will override url option when multi-language is enabled.
Segmentation
broadcast	0 - send push for targeted users using conditions (default value)
	1 - send push to everybody
conditions	Filter devices by conditions. See segment API to understand how to create conditions.
	Following options are alternative ways to create conditions.
segments	Array of segment ids used to associate a list of previously created segments
idArray	Array of XtremePush device ids that message is going to be sent to.
tokenArray	Array of device tokens that message is going to be sent to.
deviceIdArray	Array of device uuids that message is going to be sent to.
externalIdArray	Array of device external ids that message is going to be sent to.
Geo / iBeacon Campaigns
locations	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	1 - trigger on entering location
	2 - trigger on exiting location
	3 - trigger after dwell time
location_dwell_time	Integer from 1 to 30 - dwell time in minutes (required if trigger is dwell time)
location_limit_per_user	Integer - user notification limit per {location_limit_per_user_period} (1 by default)
location_limit_per_user_period	String, "campaign" or "day" - period used in {location_limit_per_user} (day by default)
location_limit_per_location	Integer - user notification limit per location per {location_limit_per_user_period} (1 by default)
location_limit_per_location_period	String, "campaign" or "day" - period used in {location_limit_per_location} (day by default)
location_limit_nth_hit	Integer - number of events needed to fire trigger (0 by default)
location_limit_nth_hit_period	String, "campaign" or "day" - period used in {location_limit_nth_hit} (day by default)
Scheduled Campaigns
send_type	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 - Time a once 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 - Date campaign should be stopped (format: YYYY-MM-DD) (optional campaign must be manually stopped if not set)
start_time	String - time of the 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 - time of the day a triggered  campaign should end (format: HH:MM) (23:59 by default)
send_days	Array - list of day numbers on which  a recurring/triggered campaign should be running (all days are specified by default)
timezone	String - timezone used for start_date, end_date, start_time, end_time attributes. If timezone is not specified then "users timezone" is used.
Push Expiry Options
retry_for	Integer. Message will not be delivered after certain period since message was sent. 4 weeks by default.
retry_for_period	String - seconds / minutes / hours / days / weeks
retry_until	Integer - unix timestamp. Message will not be delivered after certain date.
Inbox Persist Options
persist_for	Integer. Message will be removed from inbox after certain period since message was sent. Not set by default.
persist_for_period	String - seconds / minutes / hours / days / weeks
persist_until	Integer - unix timestamp. Message will be removed from inbox on certain date.

Example

Example of an Android send now broadcast campaign.

>curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN", "title": "First Android Test", "android_push": 1, "broadcast":"1", "push_title":"First Android Test", "push_text":"Testing Android Ping!"}' https://external-api.xtremepush.com/api/external/create/campaign 

Note: If you do not wish to use a segment, and would prefer to "broadcast to all users", you must set the variable "broadcast" = 1, like as shown in the example above, otherwise a segment will be created containing no conditions and your push won't be sent. 

Example of an iOS send now broadcast campaign.

curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN", "title":"First iOS Test", "ios_push": 1, "ios_push_sandbox": 1, "broadcast":"1", "push_text":"Testing iOS Ping!"}' https://external-api.xtremepush.com/api/external/create/campaign 

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

curl -X POST -d '{ "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"]]}}}' https://external-api.xtremepush.com/api/external/create/campaign 

Example of a web push campaign with the inbox message:

curl -X POST -d '{"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"}}}' https://external-api.xtremepush.com/api/external/create/campaign

 

Scheduling

If you're campaign is to be scheduled in the future it will have scheduling details in your json.

 For example 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"

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. This is still supported and you can find it in docs here

 

Multi-language 

If you need to campaign in multiple languages this is possible. Content will of course vary with language if there is to be a url for when user clicks on the message this can be shared or link to different places for different languages examples of this below.

Example post data for using the same URL for different languages:

{ 
   "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"
      }
   }
}

Example post data for using a different URL per language:

 
{ 
   "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"
         }
      }
   }
}

Send

Used to send a simple campaign i.e. one that is not automated with a schedule but is to be sent immediately when required.

URL

api/external/send/campaign

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the campaign to be sent

Example

An example of sending a campaign you have created using its id.

curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN", "id":CAMPAIGN_ID }' https://external-api.xtremepush.com/api/external/send/campaign

If your campaign sends successfully you will get the following response:

{
    "code": 200,
    "success": true,
    "message": "Campaign successfully sent",
}

If your campaign fails to send you will get a response as seen below. This can happen for a variety of reasons.

{
    "code": 400,
    "success": false,
    "message": "Failed to to send campaign",
    "errors": {
        "ios": "Upload iOS app certificate"
    }
}

 

Update

Used to update a campaign that has already been created

URL

api/external/update/campaign

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the campaign you want to update
more params	The other params are the same as those available in the create method
	Type attribute is unavailable in update method (you cannot change campaign type)

 

Remove

Used to remove a message that has already been created. Currently Only relevant for inbox messages.

URL

/api/external/remove/inbox-message

Parameters

Parameter	Description
apptoken	Your App token
campaign_id	The id of the campaign you want to remove
device_id	The device_id where you want to remove the inbox-message
user_id	The user_id where you want to remove the inbox-message
profile_id	The profile_id where you want to remove the inbox-message

Just one from the 'device_id', 'user_id', 'profile_id' parameters should be used (in a combination with campaign_id).

 

Example

Remove an inbox-message from a device:

curl -X POST -d '{"apptoken":"YOUR-APPTOKEN", "campaign_id": 2419622, "device_id":72662088}' https://external-api.xtremepush.com/api/external/remove/inbox-message

 

Example success response:

{
    "code": 200, 
    "success": true
}

 

List

Used to get a list of previously created campaigns. All campaigns may be returned or lists of campaign of a certain type if criteria are provided.

URL

api/external/list/campaign

Parameters

Parameter	Description
apptoken	Your App token
order	Order the list in either ascending or descending order based on any of the attributes e.g. "order": ["id ASC", "endtime" ] or “order”: [“id DESC”, “endtime” ]
select	Select what attributes to return e.g. "select": ["id", "title", "text"]
condition	Filter the returned push actions based on some criteria e.g. "condition": [ ["active", "=" , 1] ]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 campaigns starting at position 0
offset	Used with limit for pagination e.g. "limit": 50, "offset": 0 returns a max of 50 campaigns starting at position 0

 

Example

Get a list of all campaigns past and live.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN"}' https://external-api.xtremepush.com/api/external/list/campaign

Get a list of all live campaigns.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "condition":[["active","=",1]]}' https://external-api.xtremepush.com/api/external/list/campaign

Get all automated campaigns with a schedule live and past.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "condition":[["send_type","!=",0]]}' https://external-api.xtremepush.com/api/external/list/campaign | python -m json.tool

Get the most recently created campaign

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "limit":1, "offset":0}' https://xtremepush.com/api/external/list/campaign 

Example response showing list of campaigns

{
    "code: "200",
    "success": true,
    "data": [
        {
            "id": "CAMPAIGN_ID",
            "project_id": "PROJECT_ID",
            "title": "Test Campaign",
            ...
        },
        ...
    ]
}

 

Info

Used to get info on a single campaign.

URL

api/external/info/campaign

Parameters

Parameter	Description
apptoken	Your App Token
id	The id of the campaign you are looking for
select	Select what attributes to return e.g. "select": ["id", "title", "text"]

Example

Return the campaign info for the campaign with the given id.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "id":CAMPAIGN_ID}' https://external-api.xtremepush.com/api/external/info/campaign

Return the title, text and active attribute of the campaign with the given id.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "id":CAMPAIGN_ID, "select":["active","title","text"]}' https://external-api.xtremepush.com/api/external/info/campaign

Example of the title, text and active attribute of a campaign being returned successfully.

{
    "code": 200,
    "success": true,
    "model": {
        "active": "1", 
        "text": "Beacon Entry Test", 
        "title": "Ad location via API test"
    },
}