Introduction

General

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

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

Notification Interval

The schedule notification interval

NameValue
Daily1
Weekly2
Monthly3

 Notification status

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

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. Could be the IMEI in Android for example or UDID on iOS
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)

A unique string within this app to identify this device. Could be the IMEI in Android for example or UDID on iOS
iOSBadge Intoptiional (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)

 

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.

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.

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. Could be the IMEI in Android for example or UDID on iOS
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

 

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

 

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. Could be the IMEI in Android for example or UDID on iOS
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
PlatformFeaturesPlatformFeaturesoptionalFeatures per platform. This parameter is optional and also each field inside it is optional. 
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)
IdIntoptional

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.

 

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "Message": "hello world",
    "Link": "http://pushapps.mobi",
    "Platforms": [],
    "PlatformFeatures": {
        "AndroidTitle": "some android Title",
        "iOSBadge": 1
    },
    "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.

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. 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

6. 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 ofDeviceTypeoptionalIf 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

7. ReportUserEvent

Saving an event of a specific user. If the event is configured with notification, notifications will be sending according to the specified delay.

Request

MethodURL
POSTRemoteAPI/ReportUserEvent

Arguments

Name

Type

Description

SecretToken 

string 

mandatory

The token received from PushApps for using the Remote API

EventIdentifierstring mandatoryThe identifier of the event. If event isn't already been configured in the Admin Console, it will be created after making this request.
DeviceIdstring mandatoryDevice Id that the was set to a specific device. Mandatory if CustomId was not supplied
CustomIdstring mandatoryCustom Id that the was set to a specific device. Mandatory if DeviceId was not supplied

Request example

 

{
    "SecretToken": " YOUR SECRET TOKEN ",
    "EventIdentifier": "In_App_Purchase_1",
    "DeviceId": "12789617286112"
}

 

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


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?