Skip to content

Push with API

Message publishing API supports the following scenarios:

Scenarios
Description
Push notification from a Push Template
This approach is the simplest and yet provides the most flexibility when it comes to  identifying a dynamic audience of who will be receiving the notification, creating custom, personalized content for each recipient and configuring numerous visual and audible effects. To send out push notifications for a Push Template using the API, make sure to start with defining a Push Template first. For more information see the About Push Templates section of the guide. API Example.
Basic push notification
It is the simplest form of a push notification. It is sent to a channel and all devices registered with the channel will be receiving the notification. The notification message must contain headers which control the appearance of the notification on the devices. API Example.
Push notification delivered to devices grouped by the OS
With this type delivery, a notification is sent to all devices of a specific operating system (or a combination of).  This includes delivery to Android, iOS or both. API Example.
Push notification delivered to specific devices
This delivery type allows push notification delivery to individual devices. API Example
Delayed publishing
For all scenarios described above a push notification request can be configured to be executed at a later time. API Example.

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/<channel-name>

where:

Argument                Description
<channel-name> Name of the channel to publish the message to.

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:

Optional parameters are shown in [square brackets]:

{  
  "message" : value,  
  ["publisherId" : value,]  
"headers": {"key1":"value1","key2":"value2"}  
  ["publishPolicy":"PUSH"]  
  ["pushBroadcast" : IOS | ANDROID | ALL,] // value is a mask  
  ["pushSinglecast": ["deviceId1", "deviceId2",] // value is an array  
  ["publishAt":timestamp,] // value in milliseconds  
  ["repeatEvery":frequency-in-seconds,]  
  ["repeatExpiresAt":expiration-timestamp] // value in milliseconds  
}

where:

Argument                Description
headers Must contain headers controlling the content and appearance of the push notification on the devices.
publishPolicy If set to PUSH, message is published only as push notification, otherwise if the value is BOTH, the message is published as both push notification and a pub/sub message
pushBroadcast Must be a value calculated as an OR mask from the following constants: IOS = 1, ANDROID = 2, WP = 4, ALL = 7 (IOS
pushSinglecast Contains a JSON array of device  IDs which will be receiving the push notification.
publishAt Is a timestamp when the push notification should be sent.
repeatEvery Is a number of seconds defining the frequency of sending the notification.
repeatExpiresAt Is a timestamp when the repeat publishing operation of the push notification must stop.

Response Body

{  
  "status" : "scheduled" | "failed",  
  "messageId": messageId  
}

In order to obtain message publishing status, use the Get Message Status API with the messageId value returned by the message publishing request.

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
5003
Invalid repeatExpiresAt date
5007
User does not have the permission to publish messages
5030
Invalid publishAt date

Codeless Reference

push_push_with_api_1

where:

Argument                Description
channel name Name of the channel where a message must be published to.
device ids Must be a list containing unique identifiers of the devices that will receive a push notification.
message The contents of the message that must be published to a channel.
Android ticker text Sets the text of the ticker showing up at the top of a device's screen when the device receives the notification.
Android notification title Sets the title of the notification as it is visible in the Android Notification Center
Android notification text Sets the message of the notification which appears under android-content-title in the Android Notification Center.
iOS alert message Sets the text of the alert message. If the header is not present and the published notification targets the iOS devices, Backendless sets the header to the value of the "message" argument.
iOS badge Sets the value to update the badge with.
headers Headers control the content and appearance of the push notification on the devices.
return result When this box is checked, the operation returns an object containing the status of the message delivery and a unique message identifier.

Returns an object containing the following parameters:

// Sample object  

{  
    "messageId":"message:FCBD8BF1-A45D-4564-B449-3C91D4896987",  
    "status":"published",  
    "errorMessage":null  
}

where:

Argument                Description
messageId ID of the message for which the publishing status is retrieved.
status Can be one of the following values: FAILED, PUBLISHED, SCHEDULED, CANCELLED, UNKNOWN
errorMessage Contains a detailed error message when status is "failed".

The example below publishes the message to the "default" channel. This message is delivered only to Android devices, since no values were set for iOS properties.

push_push_with_api_2