If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

See the push notifications overview here.

Sending a Push Notification

Use a POST request to the associated URL to send a push notification.

POST https://api.appery.io/rest/push/msg

 

X-Appery-Push-API-Key is a necessary header for this service, you can find this key in the Settings section of the Push Notifications tab. As this is a POST method service, non-header parameters should be passed as request body.

If it’s not there, click Reset to generate it.

Parameters summary

Parameter Description
X-Appery-Push-API-Key Header. Unique key issued by server that allows push notifications to be sent.
expirationTime Time stamp in UTC TZ, when the provider (Apple, Google, etc.) should stop trying to send notification (if device is unavailable).
filter Parameter used for filtering devices.
options Object with push notification sending options.
payload Object that contains text message and badge.
schedule Object that contains data for scheduling.
status Indicates sent push notification instantly or schedule.

filter is an optional parameter. With the filter being empty, push notifications will be sent to all devices.

schedule is an optional parameter for immediate push notifications.

Possible errors

HTTP Status Code Description
404 PNMM004 Master Key: <pushAPIKey> not found
400 PNMM017 Message can’t be empty
400 PNMM021 Nobody is able to receive this message
400 PNMM056 Database with  id='<db_id> is not connected to push application
400 PNMM062 Badge cannot be negative
400 PNMM082 iOS Push certificate is not set
400 PNMM084 Android API key is not set
400 PNMM085 iOS Push certificate password is not set
404 PNMM088 Push notification data is too big
400 PNMM101 Empty scheduled time
400 PNMM102 Empty time zone
400 PNMM960 Specified brand is not valid

payload

Objects that contain text messages and badges.

Parameters

  • actionButtons (Android) –  a list of objects that represent buttons that will be shown a notification:
    • buttonTitle – button text;
    • buttonIcon – the image will be shown on the left side of text;
    • buttonCallback – the global function of the app. Push objects will be send as an argument.
  • badge (iOS) – the number shown with the app icon in iOS, if empty the badge will not be changed on the device.
  • color (Android) – the background color of a notification icon is supported on Android 5.0 and greater. Examples of values: red, #001100, #AA00AA.
  • contentAvailable (iOS) – if the value is 1, than app will be awakened.
  • customData – custom data that will be sent to the device.
  • icon (Android) – the main icon of the notification (it will be small, if payload.image is also added). The Image should be put into the ANDROID/project_name/res/drawable/icon_name.png location and the payload.icon should NOT have an extension.
  • image (Android) – Is shown as a large icon for Android notifications. This should be added to ANDROID/project_name/res/drawable/icon_name.png location and the payload.image should NOT have an extension. Also, the payload.image can have a link to external resource, e.g. http://exadel.com/assets/ApperyIO/appery.io_logo_221x46.png.
  • launchImage – is used as the launch image upon tapping the action button or moving the action slider.
  • message (Mandatory) – message text.
  • sound – the sound file name is to only play when a push arrives, an empty string is to be set for no sound; if not specified, the default sound is played. For iOS, sound file should be added to www/soundFileName.wav location and payload.sound should have extension. For Android, sound file should be put to res/raw/soundFileName.wav location and the payload.sound should have an extension.
  • title – title of push notification.

Example


filter

Parameter used for filtering devices. You can specify any amount of fields. All fields are chained with && (logical AND). So you can use it to narrow the list of the devices.

Parameters

  • param – any field of the _devices collection.
  • criteria – value of the param field.

Example


options

Object with push notification sending options.

Parameters

  • collapseKey – receives a custom string as a key. If set and delayWhileIdle = true, and a user’s device offline only the last push notification with the same collapse key will be received. See delayWhileIdle description.
  • dryRun – indicates that this push should be sent or if it is just testing. Native support by GCM. The service is checked from Appery.io side for iOS devices.
  • priority – the priority of the message. The value 5 for iOS is interpreted as normal for Android. Value 10 for iOS interpreted as high for Android. Setting to Default (or null in the REST request) will stipulate the default server behaviour according to the service policy (for Apple Push Notification service – 10, for Android OS – normal).
  • delayWhileIdle – The message should not be sent until the device becomes active. See collapseKey description.
  • restrictedPackageName – specifies the package name of the application where the registration tokens must match in order to receive the message.

schedule

Is when a date is selected for  when a push notification should be sent (it is always truncated to the minute). Use this parameter if you don’t want to send notifications instantly.

Parameters

  • scheduledTime – sending time in YYYY-MM-DD hh:mm:ss:mss format. Always truncates to minutes (mandatory).
  • scheduledTimeInTZ – the same time in the specified timezone; this is calculated on the server automatically.
  • timeZone – time offset in minutes that determines your time zone.
  • useDeviceTimeZone – Boolean flag that binds the sending time to the device time zone.

Example


status

This parameter can take only the sent value. It can be used instead of the schedule parameter when push notifications should be sent instantly.

Example

The schedule and status are interchangeable parameters. Don’t use the {"status":"sent"} if you want to schedule the sending of your push, otherwise notifications will be send instantly.

If the push notification is scheduled the server returns HTTP 200 and a list of the saved push notifications, otherwise the server returns with a HTTP 204 NO CONTENT status, even if no messages were sent or delivered.

Send push notification instantly

If you want to send a notification instantly you must use the status parameter with a sent value. The cURL below will immediately send the notification to all devices:

Schedule push notification

If you want to schedule the push notification use the schedule parameter. In this case, you’ll need to remove the status parameter, otherwise notifications will be sent instantly:

For the schedule you need to specify the mandatory scheduledTime parameter. You also need to specify at least one of the timeZone or useDeviceTimeZone parameters.

The value for the scheduledTime parameter must be presented in this  YYYY-MM-DDThh:mm:ss.mmm format, and it always truncates to the minute.

The timeZone parameter specifies the time offset in minutes, for example if you have an UTC +03:00 time zone, you need to specify a value of 180:

According to the values above, the push notification will be sent at 19:15 your time. At that moment all devices will get the scheduled notification, even those in another time zone. UTC +02:00 devices will receive it at 18:15, UTC +04:00 devices will receive it at 20:15, etc.

The useDeviceTimeZone parameter takes the boolean value and if it’s true, the sending time will automatically be calculated according to the device time zone. When using the useDeviceTimeZone parameter, you don’t need to specify the timeZone parameter:

In this case, all the devices will retrieve the notification at different times; when the specified scheduledTime value arrives in their time zone.

The filter parameter can be also used with scheduled push notifications. The following request configuration will send a scheduled notification only to the devices with A value in the type field:

Filtering devices

Filter is the optional parameter that determines the list of devices that will receive the notification. When it’s empty, push notifications will be sent to all devices.

The filter parameter works by any field specified in the devices collection. You can add your custom fields to this collection in the Database tab. For example, your devices collection may look as following (category field is custom):
Category

You can define several fields for the filter parameter, but remember that all fields are chained with logical AND (&&) and if at least one condition isn’t true, the others will not be accepted. On this basis, you can use several fields to narrow the devices list.

In this case, due to the request parameters, notifications will be sent instantly to devices with type = A only:

The request with the following parameters will only send notifications to the devices with type = A and in category = paid:

You can also filter the device list by the deviceID field:

List Scheduled Push Notifications

To list scheduled push notifications, send a GET request to the associated URL. Result contains only scheduled notifications that hasn’t been already sent.

GET https://api.appery.io/rest/push/msg

X-Appery-Push-API-Key is a necessary header for this service.

Parameters summary

Parameter Description
X-Appery-Push-API-Key Unique key issued by server that allows push notifications to be sent.

Possible errors

HTTP Status Code Description
400 PNML004 Push API Key: <pushAPIKey> not found
404 PNML056 Database with id='<db_id>’ is not connected to push application

Example

Remove Scheduled Push Notification

To delete a scheduled push notification, send a DELETE request to the associated URL. This REST will only remove the scheduled push that hasn’t been already sent. In other case it returns an error.

DELETE https://api.appery.io/rest/push/msg/<pushId>

Parameters summary

Parameter Description
pushId Unique identifier of push notification.

Possible errors

HTTP Status Code Description
404 PNMD100 Can’t find scheduled push with id: <pushId>
403 PNMD115 You are not permitted to perform this operation

Example

Register device

The deviceId and token parameters are automatically generated device-side. These values can’t be found anywhere except in the devices collection of the Appery.io database. Information about the device (including the deviceId and token parameters) where the app is installed, will be saved in the devices collection of the selected database as soon as the device is running the app.

See how to obtain token and deviceId (for jQuery Mobile apps).

To add the device to the database, send a POST request.

POST https://api.appery.io/rest/push/reg

The mandatory parameters are X-Appery-App-Id, deviceID, token and type.

X-Appery-App-Id can be found in the current URL:

The code after the /project/ and before the /editor is the app ID:

Parameters summary

Parameter Description
AppType App platform type (A – Android, I – iOS).
token Unique app instance identifier.
deviceId Unique device identifier.
X-Appery-App-Id Unique identifier of Appery.io application.
custom_param_name Name of custom field in _devices table.
custom_param_value Value of custom_param_name field.
channels List of channelId channel identifiers.

Possible errors

HTTP Status Code Description
400 PNDR002 App ID is not specified
400 PNDR007 Device ID must be a string
400 PNDR008 Token must be a string
400 PNDR009 Channels must be an array
400 PNDR010 Channel length can’t be more than 256 symbols
400 PNDR011 Type must be a string
400 PNDR012 Empty token/registrationID
400 PNDR013 Type must be A or I
400 PNDR014 Device ID can’t be more than 256 symbols
400 PNDR015 Project GUID: <appId> not found
400 PNDR016 Token can’t be more than 256 symbols
400 PNDR019 Channel can’t be empty
400 PNDR022 Empty deviceID
400 PNDR960 Specified brand is not valid

Example

You can provide values for other predefined or custom fields as well:

The server returns an HTTP 200 OK status and the registered device identifier, if the device was successfully registered.

Get device

To get device info from the database, send a GET request with device ID at the end of the URL.

GET https://api.appery.io/rest/push/reg/<deviceId>

The get device service can be used for retrieving information about the device stored in the devices collection. The response of this service is JSON, which contains all predefined and user-defined fields of the devices collection. This service can be handy when you need to get the deviceID, check its timeZone, or for any other operation involving device info.

The deviceID can be found in the predefined devices collection of the Appery.io database.

In the devices collection of the Appery.io database, the deviceID field contains a semicolon. (For libraries 3.0 (JQM) and higher the semicolon is not used.) Replace it with %3B to properly send the request, as shown here:

The URL with the device ID at the end looks like:

Parameters summary

Parameter Description
deviceId Unique device identifier.
X-Appery-App-Id Unique identifier of the Appery.io application.

Possible errors

HTTP Status Code Description
400 PNDG002 The application ID isn’t specified
404 PNDG006 Device ID: <deviceId> not found
400 PNDG006 Project GUID: <appId> not found
400 PNDG960 Specified brand is not valid

Example

The only parameter required to invoke a GET request is X-Appery-App-Id.

After the service testing, you’ll get a JSON response with device info.

Update device

To update the device, send a PUT request to the associated URL with the device ID at the end:

PUT https://api.appery.io/rest/push/reg/<deviceId>

The update device service is for updating information about any device stored in the devices collection. This service can be used for updating any collection field. For example, it can be timeZone, channels or category (which is a user-defined field).

Parameters summary

Parameter Description
type Application platform type (A – Android, I – iOS).
token Unique app instance identifier.
deviceId Unique device identifier.
X-Appery-App-Id Unique identifier of Appery.io application.
custom_param_name Name of custom field in _devices table.
custom_param_value Value of custom_param_name field.
channels List of channelId channel identifiers.

Possible errors:

HTTP Status Code Description
400 PNDU002 App ID not specified
404 PNDU006 Device ID: <deviceId> not found
404 PNDU015 Project GUID: <appId> not found
400 PNDU960 Specified brand is not valid

Example

The following example shows how to update channels column of the specific device. The channels column of the predefined devices collection has an array type. Any new value for this column must be also sent as an array. Any other parameter can be updated the same way.

The X-Appery-App-Id header is a necessary parameter for this request. Other fields are optional. You can specify any field that exists in the devices collection.

Unregister device

To delete the device from the database, send a DELETE request to the associated URL with the device ID at the end.

DELETE https://api.appery.io/rest/push/reg/<deviceId>

Parameters summary

Parameter Description
deviceId Unique device identifier.
X-Appery-App-Id Unique identifier of the Appery.io application.

Possible errors

HTTP Status Code Description
400 PNDD002 App ID not specified
404 PNDD006 Device ID: <deviceId> not found
404 (400) PNDD015  Project GUID: <appId> not found
400 PNDU960 Specified brand is not valid

Example

Make sure you use the DeviceID containing the %3B value. The server returns the response field with no content.