The syntax of the create method has been simplified in an updated version so we recommend you use that found in docs here.
If you have already completed your integration the approach in the create method documented below is still fully supported.
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
- 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 |
| type | Integer, campaign type |
| 0 - simple campaign | |
| 1 - geo / ibeacon campaign | |
| 2 - in-app campaign (contact us if you want to use this type) | |
| Push Message Parameters | |
| text | The text of your push message |
| payload_add | Used to add payload (key,value) pairs |
| Linked Content Parameters | |
| 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. |
| 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. |
| OS Specific Parameters | |
| android[active] | Boolean 0/1 where, 1="should be sent to Android devices" (0 by default) |
| ios[active] | Boolean 0/1 where, 1="should be sent to iOS devices" (0 by default) |
| ios[environment] | String - "sandbox" or "production" ("production" by default). |
| Filter devices by gateway and defines gateway for sending push notifications. | |
| Segmentation Parameters | |
| 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) |
| Schedule Parameters | |
| 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. usage - timezone: "Europe/Dublin" If timezone is not specified then "users timezone" is used |
Example
Example of an Android send now campaign.
curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN","broadcast":"1","title":"First Android Test", "text":"Testing Android Ping!", "android": {"active":1},"send_type":0}' 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 campaign.
curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN","broadcast":"1","title":"First iOS Test", "text":"Testing iOS Ping!", "ios": {"active":1}, "send_type": 0}' https://external-api.xtremepush.com/api/external/create/campaign
Example of an iOS send now campaign with a payload, and a flag is on condition attached.
curl -X POST -d '{ "apptoken":"YOUR_APPTOKEN","send_type": 0, "title":"El Classico", "text":"1-0! Messi scores.", "payload_add":[{"key":"score", "value":"1-0"}], "ios":{"active":1}, "conditions":{"operator": "AND", "0":{"operator":"AND", "0":["tags_flag","=", "live_scores",["status","=","on"]] }}} https://external-api.xtremepush.com/api/external/create/campaign
Example response showing the campaign being successfully created. If you need to send this campaign with the send method you must retrieve it's id from the returned JSON.
{ "code": 200, "message": "Campaign successfully created", "model": { "id": "CAMPAIGN_ID", "project_id": "PROJECT_ID", "active": 1, "send_type": 0, "trigger": 0, "title": "El Classico", "text": "1-0! Messi scores.", "payload_add": { "score": "1-0" }, "url": null, "url_browser": 0, "page": null, "ios": { "active": 1 "environment": "production", "badgeCount": "", "customSound": "" }, "android": { "active": 0, "customSound": "" }, "conditions": { "0": { "0": [ "tags_flag", "=", "live_scores", [ "status", "=", "on" ] ], "operator": "AND" }, "operator": "AND" }, }, "success": true }
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 location campaign that can be triggered at anytime for a number of days 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",
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) |
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", "active": 1, "send_type": 2, "title": "Test Campaign", "text": "Hi there!", ... }, ... ] }
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" }, }
Comments
0 comments
Article is closed for comments.