Skip to content

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:

The API registers a device with Backendless. Before the API is used, the device must be registered with APNS (Apple Push Notification Service) for the iOS devices and FCM (Firebase Cloud Messaging) for the Android devices. This must be done using native code as JavaScript does not have a built-in capability to perform device registration with APNS/FCM. As a result of the device registration with APNS/FCM, your application receives a registration token which must be used as the first argument in the API call documented below:

Backendless.Messaging.registerDevice( deviceToken, 
                                      channels, 
                                      expiration )
 .then( function( response ) {
  })
 .catch( function( error ) {
  });

where:

Argument                Description
deviceToken device token obtained from APNS or FCM;
expiration a timestamp when the device registration should expire;
channels an array of channel names to receive messages from. If a value is not provided, Backendless  registers the device with the default channel;

Return value

A JavaScript object containing information about the registration of the device with each channel referenced in the body of the request. If the request does not specify any channels, the response includes information about the registration with the default channel:

{
  registrationId : "<REGISTRATIONID1>::<CHANNELNAME>,<REGISTRATIONID2>::<CHANNELNAME>"
}

For example, suppose the device registration request is for two channels: channel1 and channel2. The response would be as shown below:

{
  registrationId : "DDB739FA-7B8C-A865-FFBC-63B746A1E200::channel1,1FC8C91C-A0DD-C130-FFCB-88C34A235E00::channel2"
}

where DDB739FA-7B8C-A865-FFBC-63B746A1E200 is the device registration ID for channel1 and 1FC8C91C-A0DD-C130-FFCB-88C34A235E00 is the device registration ID for channel2.

Errors:

The following errors may occur during the message publishing API call. See the Error Handling section for details on how to retrieve the error code when the server returns an error:

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.