Push Notification Methods

The push notification methods are used to get info about the push notifications sent out by campaigns. Simple campaigns will send out a single batch of notifications at once. However, more complex campaigns will send out batches of notifications at varying intervals over the lifetime of the campaign. For example a location based campaign can send single notifications to individual devices as they enter locations while the campaign is running. Each individual event for a campaign where push notifications are sent is known as a Push Notification Action. Available Methods are:

• List: Query existing push notification actions and get a list of results
• Info: Get info on a single push notification action

List

Used to get a list of all the push notification actions related to campaigns. All actions may be returned or lists of actions of a certain type if criteria are provided.

Options

The list method can return summary information on the push action or more detailed information on notifications sent to individual devices using the following options:

• list/push
• list/-push-device

URL (/push)

api/external/list/push

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", "runtime" ] or "order": ["id DESC", "runtime" ]
select	Select what attributes to return e.g. "select": ["message", "message_id"]
condition	Filter the returned push actions based on some criteria e.g. "condition": [ ["message_id", ">" , 1] ]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 push actions starting at position 0
offset	Used with limit for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 push actions starting at position 0

Example

Return all push notification actions:

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

Return the id and message attributes of all push actions:

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN",  "select": ["message", "message_id"] }' https://external-api.xtremepush.com/api/external/list/push

Return the push notification actions that were updated since the 1 Jan 2015 (using Unix time 1420070400).

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN",  "condition": [["update_time", ">", "1420070400"]] }' https://external-api.xtremepush.com/api/external/list/push | python -m json.tool

JSON response for a single push notification action, a notification sent to an iOS device.

{
    "code": 200,
    "success": true,
    "data": [
        {
            "id": PUSH_ID,
            "project_id": PROJECT_ID,
            "campaign_id": CAMPAIGN_ID,
            "type": "ios",
            "environment": "android",
            "message": {
                "alert": "Test",
                "badge": "",
                "id": PUSH_ID,
                "sound": "default",
                "special": "payload"
            },
            "error": 0,
            "error_message": null,
            "sent_count": 10,
            "error_count": 1,
            "open_count": 5,
            "create_time": "1421601226",
            "update_time": "1421601226",
        },
        ...
    ],
}

 

URL (push-device)

api/external/list/push-device

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", "runtime" ] or "order": ["id DESC", "runtime" ]
select	Select what attributes to return e.g. "select": ["message", "message_id"]
condition	Filter the returned push actions based on some criteria e.g. "condition": [ ["message_id", ">" , 1] ]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 push actions starting at position 0
offset	Used with limit for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 push actions starting at position 0

Example

 

Return the action_id, campaign_id, create_time, device_id and error_message for no more than last 50 failed messages from  a given campaign if any.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", 
"condition":[["campaign_id", "=" , YOUR_CAMPAIGN_ID],
             ["error", "=" , 1]],
"order": ["id DESC", "create_time" ], "limit":50, "offset":0, 
"select": ["campaign_id","action_id",
"message","create_time","device_id","error_message"]}' 
https://external-api.xtremepush.com/api/external/list/push-device

Sample JSON response for this example below. You can see some notifications failed, and that the reasons vary; some users were missing attributes for personalisation and consequently a notification could not be sent, and some users had uninstalled the application.

{
    "code": 200, 
    "data": [
        {
            "action_id": 21714179, 
            "campaign_id": 245624, 
            "create_time": 1485883608, 
            "device_id": 17186391, 
            "error_message": "Not personalized"
        }, 
        {
            "action_id": 21687974, 
            "campaign_id": 245624, 
            "create_time": 1485876298, 
            "device_id": 17186391, 
            "error_message": "Not personalized"
        }, 
       
        {
            "action_id": 15257795, 
            "campaign_id": 245624, 
            "create_time": 1480674210, 
            "device_id": 7039393, 
            "error_message": "DEVICE_UNREGISTERED"
        }, 
        {
            "action_id": 8958858, 
            "campaign_id": 245624, 
            "create_time": 1474649166, 
            "device_id": 7039393, 
            "error_message": "Application is Uninstalled"
        }, 
        {
            "action_id": 8762755, 
            "campaign_id": 245624, 
            "create_time": 1474450109, 
            "device_id": 7039393, 
            "error_message": "Application is Uninstalled"
        }, 
        {
            "action_id": 1250084, 
            "campaign_id": 245624, 
            "create_time": 1467728373, 
            "device_id": 3941948, 
            "error_message": "Application is Uninstalled"
        }, 
        {
            "action_id": 759147, 
            "campaign_id": 245624, 
            "create_time": 1464355910, 
            "device_id": 4599293, 
            "error_message": "Application is Uninstalled"
        }
    ], 
    "success": true
}

 

Info

Used to get info on a single push notification action.

URL

api/external/info/push

Parameters

Parameter	Description
apptoken	Your App Token
id	The id of the push notification action you are looking for
select	Select what attributes to return e.g. "select": ["message", "message_id"]

Example

Get all info on the push notification.

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

JSON response with info for a requested push notification action.

{
    "code": 200,
    "success": true,
    "model": {
        "id": PUSH_ID,
        ...
    },
}