Page tree
Skip to end of metadata
Go to start of metadata

 

Introduction

General

  • Base URL for all methods is : https://ws.pushapps.mobi/
  • Dates are according to UTC timezone and formatted as ISO strings according to the following format: yyyy-MM-ddTHH:mm:ssZ

    Format specifierDescription
    yyyyThe year as a four-digit number.
    MMThe month, from 01 through 12.
    ddThe day of the month, from 01 through 31.
    HHThe hour, using a 24-hour clock from 00 to 23.
    mmThe minute, from 00 through 59.
    ssThe second, from 00 through 59.
    ZUsed to indicate the date is in UTC timezone

Understanding the difference between DeviceId and CustomId

By using the remote API, we give you the option the add your own custom Id to each device, which can be used instead or in addition to the DeviceId which is supplied by the SDK. As a rule, CustomId receives higher priority than DeviceId in your API requests.

Request Object

  • All requests are HTTP POST.
  • All request body is a JSON formatted string of the parameters.
  • All request parameters are mandatory unless explicitly marked as [optional].
  • All requests must have the SecretToken parameter which is obtained from the PushApps system - If you are not familiar with it please read Getting started with the Remote API.

Response Object

The response body is a JSON formatted string, which represents the following object:

NameTypeDescription
CodeIntmandatoryone of our Status codes, listed for each request
MessageStringmandatorymessage explaining the code
DataObjectoptionalused in some methods to provide more data

If the response is not specifically mentioned it does not contain the Data field.

Example:

 

{
  "Code": 100,
  "Message": "OK",
  "Data" : { "SomeKey" : "SomeValue" }
}

 

Enums

DeviceType

The device's platform type

NameValue
Android1
iOS2

SDKType

The device's sdk type

NameValue
Android Native1
iOS Native2
Android Phonegap3
iOS Phonegap4
Android Titanium5
iOS Titanium6
Android Corona7
iOS Corona8

NotificationInterval

The schedule notification interval

NameValue
Daily1
Weekly2
Monthly3

NotificationStatus

The notification current status

NameValueDescription
Not Sent1Notification not sent yet.
Sending2Notification is in sending process
Received3Notification received by the application user
Opened4Application's user clicked and opened the notification
Failed5Failed to send notification
Push Token Expired6Application's user haven't logged in to application for a long time and his push token is no longer valid
Disabled7Notification has canceled due to user's request
Subscription Changed8Application's user's push token has been changed, notification is sent. (Android Only)
Wrong Service Credentials9For android platform -> GCM_API_Key might be invalid , iOS platform -> Corrupted P12 file or bad certificate

TagType

Available types for tags

NameValue
Date1
Number2
String3
Boolean5

Objects

 Device

A device, which will be the target of the notification

NameTypeDescription
PushTokenStringmandatoryThe token received from Google or Apple for the device
DeviceIdStringmandatoryA unique string within this app to identify this device. available through our Mobile SDK
DeviceTypeDeviceTypemandatorythe device platform type

PlatformFeatures

Platform specific features for a notification. When adding them to a request the SDK will act according to the requested features.

NameTypeDescription
AndroidTitle String

optiional (default will be the application name

on the device)

the token received from Google or Apple for the device
AndroidSoundString

optiional (default will be be the default

system notification sound)

name of the sound file to play when receiving a notification. File

must be placed inside the raw folder of the app.

iOSBadge Stringoptiional (default is 1)the device platform type
iOSSoundStringoptiional (default is "default")

name of the sound file to play when receiving a notification (empty string will cause the notification to be silent)

iOSContentAvailableStringoptional (default it empty )set this to "1" in order to send iOS silent notifications, there will be no alert or sound shown. Omit this field or set to "0" for a regular notification.

SchedulingFeatures

Scheduling features allows you to send your notification on a specific date or/and with a number of occurrences. This is an optional feature that can be added to the base of the notification request.

Important

if EndDate and Occurrences aren't supplied, the EndDate will automatically will be 'Never' and the sending will never be stopped.

NameTypeDescription
IntervalNotificationInterval

Interval that determines the delay between each sending

EndDate

ISO formatted String, in UTC timezone, format

is yyyy-MM-ddTHH:mm:ssZ

optional, the end date of the schedule notification.

OccurrencesIntoptional, times the notification will be sent
StartDate

ISO formatted String, in UTC timezone, format

is yyyy-MM-ddTHH:mm:ssZ

optional (default is now), the time for the first notification
ConsiderDeviceTimeZoneBoolean

optional (default is false), sending the notification on the provided time according to the device's time zone.

Dates should be in UTC timezone 

Methods

1. RegisterDevice

Register a specific device in the system

Request

MethodURL
POSTRemoteAPI/RegisterDevice

Arguments

NameTypeDescription
SecretToken StringmandatoryThe token received from PushApps for using the Remote API
PushToken StringmandatoryThe token received from Google or Apple by the device
DeviceId Stringmandatory (not needed only ifCustomId was used)A unique string within this app to identify this device. available through our Mobile SDK
CustomIdStringmandatory (not needed only if DeviceId was used)Custom id that represents the device.
DeviceType DeviceTypemandatory 
OSVersion StringoptionalThis device operating system version
SDKVersion StringoptionalPushapps sdk version
DeviceDescription StringoptionalThe hardware of the device, i.e "iPhone 5"
AppVersion StringoptionalThis app current version
TimeZoneIntoptionalThe device's offset from UTC in minutes. For example, UTC +01:00 will be 60
SdkTypeSdkTypeoptionalThe device's sdk type
AppIdentifierStringoptionalThe Package Name (Android) / Bundle Id (iOS) of the application

 

Request example

 

{
"SecretToken": "YOUR SECRET TOKEN",
"PushToken": "some push token",
"DeviceId": "79848",
"CustomId": "nbf674m79gd83db",
"DeviceType": 2,
"OSVersion": "7.1",
"DeviceDescription": "iPhone 5s",
"SDKVersion": "1",
"AppVersion" : "3.1.3",
"SdkType" : 2,
"AppIdentifier" : "com.pushapps.demoapp"
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error

2. UnregisterDevice

Unregister a specific device in the system, using the device id or custom id supplied when it was registered

Request

MethodURL
POSTRemoteAPI/UnregisterDevice

Arguments

NameTypeDescription
SecretToken StringmandatoryThe token received from PushApps for using the Remote API
DeviceId Stringoptional (you must use either this or CustomId)A unique string within this app to identify this device. available through our Mobile SDK
CustomIdStringoptional (not needed if DeviceId was used)Custom id that represents the device.

Request example

 

{
"SecretToken": "YOUR SECRET TOKEN",
"DeviceId": "79848"
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

109

The requested device does not exist

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error

3. CreateNotification

Creates an immediate notification in the system, for all the devices registered for this app, or by platforms, or for an array of devices, or by an array of device ids or custom ids.

Request

MethodURL
POSTRemoteAPI/CreateNotification

Arguments

NameTypeDescription
SecretToken String mandatoryThe token received from PushApps for using the Remote API
MessageString mandatoryThe content of the message
PlatformsArray of DeviceTypeoptionalThe platforms this notification will be sent to. If not set or empty the notification will be sent to all platforms
DevicesArray of Device

optional

If not supplied or empty, the notification will be sent to all available devices according to the selected platforms
DeviceIdsArray of Strings

optional

 

If supplied, message will be delivered to supplied deviceIds. 
Cannot be used along with CustomIds.
CustomIdsArray of Strings

optional

If supplied, message will be delivered to supplied CustomIds. 
Cannot be supplied with DeviceIds.
LinkStringoptionalIf exists the device will open a browser with the URL specified here
PlatformFeaturesPlatformFeaturesoptional

Features per platform. This parameter is optional, but once used some of its fields are mandatory:

  • iOSBadge - If PlatformFeatures is used but iOSBadge isn't, the current application badge will remain the same.
  • iOSSound - If PlatformFeatures is used but iOSSound isn't, no sound will be used ( silent notification ).

Default values, in case PlatformFeatures is not used at all:

  • iOSBadge - 1
  • iOSSound - default
  • iOSCategory - none
  • iOSContentAvailabe - empty
  • AndroidTiltle - the application's name
  • AndroidSound - the default notification sound of the device
CustomJsonKeyStringoptionalThe key in the data object received in the push notification. If you supply a CustomJsonKey you must supply the CustomJson as well
CustomJsonStringoptionalThe value of the data object received in the push notification. can be either a JSON formatted string or a regular string. if you supplyCustomJson and don't supply a CustomJsonKey we will use our default key (D)
IdStringoptional

Add more devices to a specific notification by the notification id you receive from us.Use this If you need to send notifications to specific devices that are more than 10,000 devices. you will receive this id in your first request's response. afterwards call the request with more devices as many times as you need, always using the same Id.

SchedulingSchedulingFeaturesoptionalScheduling features allows you to plan further ahead your notifications by setting the send date to a specific day and adding number of occurrences.
SegmentIdStringoptionalNotification will be delivered to devices associated with this segment. Cannot be used along with Devices or DeviceIds

 

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Message": "hello world",
    "Link": "http://pushapps.mobi",
    "Platforms": [],
    "PlatformFeatures": {
        "AndroidTitle": "some android Title",
"AndroidSound" : "myCustomSound.ogg",
        "iOSBadge": 1,
"iOSSound" : "default",
"iOSCategory" : "Yes No",
"iOSContentAvailable" : "0"
    },
    "CustomJsonKey": "myKey",
    "CustomJson": "{
        "someKey": "someVal"
    }",
    "Devices": [
        {
            "PushToken": "APA91bE1ta3vuTW63-pDxpb8YOLWdw846XD5EprodjCAOHg3dx-GDTc-UvrarmtoYZpgqMAVIbLv-CPIuemg2P42edeKqb4rIq-HhViU2kGeW5qWEMitcE83qn-rIy4Lnzu7GclKdc5nhJLHqTwy8m0fkBMfF1zGpc1ME_gisIS_t25muUJDCPY",
            "DeviceType": 1
        },
        {
            "PushToken": "c3b24fdc7b7a6a449e2f7c4b311c62cd0189378a4774519ae3c1c0f5dde532a4",
            "DeviceType": 2
        }
    ],
    "DeviceIds": [
        "359372043909118"
    ],
    "Scheduling": {
        "StartDate": "2014-05-12T13:00:00Z",
        "EndDate": "2014-06-12T13:00:00Z",
        "Interval": 1
    }

 

 

}

 

Response example

 

{
  "Code": 100,
  "Message": "OK",
  "Data": {
    "Id": 3760
  }
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

103

The .P12 file needed to complete the operation wasn't found. Please check for active .P12 file for your gateway.

104

Cannot sent notification to application without users

105

iOS payload is too large

106

Application does not have any components

110

Android device is not yet configured for this app

113

Sending notification with custom parameters is limited to 10,000 users. Use provided Id to insert maximum of 10,000 users per request.

116

You provided more than 1 option to send notification. Please choose only 1. ( For example, you can't provide both the Platforms with any of the Devices , DeviceIds, CustomIds parameters )

118Cannot send scheduled notification to specific users.
119Cannot add more devices to scheduled notification.
121Could not find devices by provided data.
122One or more of the platforms provided is unknown.

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error

4. GetNotificationsForDevice

Gets all notification that were sent to a specific device by either DeviceId or by CustomId.

Request

MethodURL
POSTRemoteAPI/GetNotificationsForDevice

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

Amount

Int

optional

Amount of the notifications returned, if not supplied returns max amount of notifications which is equal to 1000.

Index

Int

optional

If supplied, returns a response from the given index. If not supplied, returns from the first index. Lowest index value is 1.

DeviceId

string 

mandatory

Device Id that the was set to a specific device. You can supply it in addition to CustomId or without it.

CustomId

string

mandatory

Custom Id that the was set to a specific device. You can supply it in addition to DeviceId or without it.

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Amount": 3,
    "Index": 1,
    "DeviceId": "SOME DEVICE ID",
    "CustomId": "SOME DEVICE CUSTOM ID"
}

 

Response example

 

{
    "Code": 100,
    "Message": "OK",
    "Data": {
        "Index": 3,
        "HasMore": true,
        "Notifications": [
            {
                "Date": "2013-10-15T13:29:40Z",
                "Message": "Hello World!",
                "Status": 4
            },
            {
                "Date": "2013-10-16T16:38:29Z",
                "Message": "This is my message",
                "Status": 3
            },
            {
                "Date": "2013-10-17T08:12:40Z",
                "Message": "Hello World!",
                "Status": 3
            }
        ]
    }
}

 

HasMore = true  indicates that there are more results for this request that were not able to be sent due to the Amount argument value. You should call this request again with the Index received to get more results starting from that index.

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

111

Device's CustomId is too large, Limited to 100 chars.

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


5. DeleteNotification

Delete a notification that was sent to a specific device.

Request

MethodURL
POSTRemoteAPI/DeleteNotification

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

NotificationId

string

mandatory

The Id of the notification that the was sent to the device. Notice that this is not the same Id that your receive from CreateNotification which identifies an entire campaign but the specific id that the devices received in the notification

 

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "NotificationId": "11456783",
}

 

Response example

 

{
    "Code": 100,
    "Message": "OK"
}

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error

6. SetDeviceWithCustomId

Sets a custom id for a specific device by its DeviceId. This is used for future analysis and fetching data
(i.e : GetNotificationsForDevice).

Request

MethodURL
POSTRemoteAPI/SetDeviceWithCustomId

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

DeviceId

string 

mandatory

Device Id that the was set to a specific device.

CustomId

string

mandatory

Custom Id that you want to set to the specific device

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "DeviceId": "SOME DEVICE ID",
    "CustomId": "SOME DEVICE CUSTOM ID"
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

109

The requested device does not exist

111

Device's CustomId is too large, Limited to 100 chars.

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error

7. GetDevices

Gets all app users for application either by their DeviceType or all of them.

Request

MethodURL
POSTRemoteAPI/GetDevices

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

AmountintoptionalAmount of the users returned, if not sent returns max amount of users which is equal to 1000.
IndexIntoptionalIf supplied, returns a response from the given index. If not supplied, returns from the first index. Lowest Index value is 1.
PlatformsArray of DeviceTypeoptionalIf supplied, return users matching the given platforms. If not supplied returns users regardless of their platforms

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Amount": 3,
    "Index": 1,
    "DeviceTypes": [
        2
    ]
}

 

Response example

 

{
    "Code": 100,
    "Message": "OK",
    "Data": {
        "Index": 2,
        "Devices": [
            {
                "PushToken": "cd0189378a4774519ae3c1c1j9dde532a4",
                "DeviceId": "2C18D56E-4E18-42C5-8771-2g27E464A358",
                "CustomId": "511",
                "DeviceType": 2,
                "TimeZone": 0
            },
            {
                "PushToken": "b8b37b6ee2039e36774d2aa2651674f430ac571a4085d",
                "DeviceId": "92B06DB6-A3DE-4C99-8D02-37C9FA59C825",
                "CustomId": "1404",
                "DeviceType": 2,
                "TimeZone": 0
            }
        ]
    }
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


8. CheckIOSPayload

Check your notification payload before sending it. iOS payload is a limit determined by Apple and is now set to 255 Bytes

Request

MethodURL
POSTRemoteAPI/CheckIOSPayload

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

Message

string mandatoryThe message itself
Linkstring optionalThe Url that will be opened via user’s browser when clicking on the notification.
CustomJsonKeystring optionalThe key in the data object received in the push notification. If you supply a CustomJsonKey you must supply the CustomJson as well
CustomJsonstring or JSON formatted stringoptionalThe value of the data object received in the push notification. can be either a JSON formatted string or a regular string. if you supplyCustomJson and don't supply a CustomJsonKey we will use our default key (D)

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Message": "Hello World",
    "Link": "http://www.google.com",
    "CustomJson": "<your json>"
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

105Ios payload is too large

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


9. GetNotificationStatistics

Get statuses for notification. if the notification is a campaign, such as a scheduled notification, all sent notifications are returned and presented by their Create Date field.

Request

MethodURL
POSTRemoteAPI/GetNotificationStatistics

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

IdintmandatoryId of the notification received when creating notification via Remote Api OR in the statistics tab under Notification Details

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Id": "46712"
}

 

Response example

 

{
"Code": 100,
"Message": "OK",
"Data": {
"Notifications": [
{
"Statuses": [
{
"Status": "Active Devices",
"Amount": 34
},
{
"Status": "Delivered",
"Amount": 30
},
{
"Status": "Invalid Push Token",
"Amount": 2
},
{
"Status": "Android Mismatch Sender Id",
"Amount": 2
}
],
"CreateDate": "2014-09-26T07:35:50Z"
}
]
}
}

 

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

120Could not find notification by provided data.

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


 

10. GetNotificationFailedDevices

Get status for each device which failed to receive a notification. if the notification is a campaign, such as a scheduled notification, all the instances of notifications that were already sent will be returned in the response and each will contain the devices which failed to get the notification.

If having more than 1000 results (max Amount per request/response), it is possible to keep requesting more devices by increasing the Index by 1 until there will be no more results.

Request

MethodURL
POSTRemoteAPI/GetNotificationFailedDevices

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

IdintmandatoryId of the notification received when creating notification via Remote Api OR in the statistics tab under Notification Details
AmountintoptionalMax quantity of devices per request, default is 1000
Indexintoptionalpage index, 1 based. default is 1.

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Id": "51212",
    "Amount": "2",
    "Index": "1"
}

Response example

 

{
    "Code": 100,
    "Message": "OK",
    "Data": {
        "Notifications": [
            {
                "Devices": [
                    {
                        "PushToken": "APA91bFXeTqBFBmP2ScoQRY-jMWeRp9N5ubIbOJCdxzFlovvMcyzuLWWTmDn1TDuKQwDMySgkXyfKyTFKMaDAAXtX2TfN6oeea4JnaeXmUWYJ8KTLlolpWFl7M4SRwHzKmqmHP0VjXno42IqqVJibo7O_044BKygmQ",
                        "DeviceId": "359372043909181",
                        "Status": "Android Mismatch Sender Id",
                        "MobileType": 1
                    },
                    {
                        "PushToken": "2da19609241734e7a53c66f542fcf8b5b206789deafb07d64ac4b65052f0653e",
                        "DeviceId": "B964513C-058C-4048-802D-E468AD8464DD",
                        "Status": "iOS Certificate Expired",
                        "DeviceType": 2
                    }
                ],
                "CreateDate": "2014-07-08T07:42:00Z"
            }
        ]
    }
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

120Could not find notification by provided data.

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


11. UpdateCampaignStatus

Update your scheduled or triggered notifications status, either pause, resume or delete it.

Request

MethodURL
POSTRemoteAPI/UpdateCampaignStatus

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

Id

intmandatoryThe Id given by PushApps server when creating a notification via the remote API or either by the client interface.
Statusstring mandatoryThe status that the campaign should be set to. can be either "Resume", "Pause" or "Delete". Not case sensitive.

 

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Id": "10254",
    "Status": "Resume"
}

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


12.GetAppSegments

Gets all segments associated with your application.

Request

MethodURL
POSTRemoteAPI/GetAppSegments

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
}

 

Response example

 

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


13.SetTag

Sets a tag value for a specific device. If the tag was never created a new tag will be created.

Request

MethodURL
POSTRemoteAPI/SetTag

Arguments

Name

Type

Description

SecretToken 

String 

mandatory

The token received from PushApps for using the Remote API

IdentifierStringmandatoryAn identifier for the tag, if the identifier does not exist, a new tag is created with this identifier and type
ValueStringmandatoryThe value to associate to this tag for this device. For Boolean use "true" or "false", for Date use our date format as described at the top of this article
TypeTagTypemandatorythe type of this tag
DeviceIdStringmandatoryA unique string within this app to identify this device. available through our Mobile SDK

Request example

 

 

Response example

 

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

125Tag type cannot be changed once created
126Illegal Value for this tag type

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


14.RemoveTag

Removes the tag value for a specific device

Request

MethodURL
POSTRemoteAPI/RemoveTag

Arguments

Name

Type

Description

SecretToken 

String 

mandatory

The token received from PushApps for using the Remote API

IdentifierStringmandatoryAn identifier for the tag, if the identifier does not exist, a new tag is created with this identifier and type
DeviceIdStringmandatoryA unique string within this app to identify this device. available through our Mobile SDK

Request example

 

 

Response example

 

 

Available status codes

Status

Message

100

OK 

101

One parameter at least is missing or wrong

102

The input is not well formatted

127Tag does not exist

200

You are not authorized for this action, please check the credentials again or contact support

900

There has been a service error


Callbacks

You can provide callback URL through the Admin Console to listen for events in the system.

For more information regarding callbacks please visit Using callbacks

 

What's next?

  • After reading through the API reference, you can start diving into some coding.