Device Registration API

In order to receive push notifications from Backendless, a device must be registered using the API documented below. Device registration may optionally include a list of messaging channels and/or an expiration date/time when the registration should be canceled.

Important

Push notifications can be published using either API or Backendless Console. When a push notification is published, it goes through a * messaging channel* . Channels provide a way to establish a level of filtering - devices registered with a channel will receive notifications published to the channel. However, there are other way to narrow down push notification delivery. For example, a push notification may be sent to a specific device or a group of devices.

If no channels are specified in the device registration call, Backendless registers the device with the default channel. If the device registration call references a non-existing channel, Backendless creates the channel and registers the device with it. Registration expiration is a point in time (expressed as a timestamp) when the device registration must expire. Backendless removes the device registration at the specified time and the device no longer receives published push notifications.

In order to receive push notifications on a mobile device, application running on the device must register with Backendless using the API call below:

Method

POST

Endpoint URL

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/messaging/registrations

Request Headers

Content-Type: application/json  
user-token: optional value obtained as a result of the login operation.

where:

Argument	Description
Content-Type	Must be set to application/json. This header is mandatory.
user-token	Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the operation will be executed with the security policy associated with the currently logged in user. This means all permissions associated with the user and the roles assigned to the user will be enforced by Backendless.

Request Body:

{  
  "deviceToken" : value,  
  "deviceId" : value,  
  "os" : "IOS" | "ANDROID" | "WP",  
  "osVersion": value  
  [,"channels": [channelName1, channelName2]],  
  [,"expiration": timestamp in GMT0]  
}

where:

Argument	Description
deviceToken	A token assigned by the push notification service provider (Google Cloud Messaging or Apple Push Notification Service).
deviceId	A unique identification of the device where push notifications will be delivered to.
os	Operating system identifier
osVersion	Version of the operating system
channels	An array of Backendless messaging channels to associate the device with. If the property is not included into the request payload, the device is registered with the default channel.
expiration	A timestamp indicating when the device registration should expire.

Response Body

{  
  "registrationId" : value  
}

Errors

When the server-side reports an error, it returns a JSON object in the following format:

{  
  "message":error-message,  
  "code":error-code  
}

The following errors may occur during the message publishing API call:

Error Code	Description
5004	Invalid expiration date. The expiration date must be after the current time.
8000	Property value exceeds the length limit. Error message should contain additional details about the violating property.

Example

Important

Make sure to replace xxxx in the domain name in the sample request below to the one assigned to your application.

curl \  
-H Content-Type:application/json \   
-X POST \  
-d '{ \  
   "deviceToken":"XXXXXXXXXXXXXXXXXXXXXXXXX", \  
   "deviceId":"XXXXXXXXXXXXXXXXXXXXXXXXX",    \  
   "os":"ANDROID",  \  
   "osVersion":"4.1" \  
   }' \  
-v https://xxxx.backendless.app/api/messaging/registrations

Codeless Reference

where:

Argument	Description
channel name	A list of messaging channels the device registration will be associated with. Messages published to the channels will be delivered to the associated devices. If no values are passed to this parameter, then Backendless registers the device with the default channel.
return result	Returns an object with the registrationId parameter, containing a Map between Backendless channel name (key name in the map) and the registration ID of the device for that channel (value assigned to the key). When a device is registered with multiple Backendless messaging channels, this map will contain a mapping for each channel.

The example below registers the device with the "ads" and "discount" channels: