Skip to content

General API

A Backendless application can publish messages to Backendless for subsequent distribution to subscribers. A message must be published to a channel. Backendless supports unlimited number of channels per application. Channels can be used as a filtering mechanism - subscribers see the messages published only to the channel they subscribe to.

There is only one API for all types of message publishing. It supports the following scenarios:

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 the permissions and 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"},]  
  ["publishAt":timestamp,]  *// the value in milliseconds*  
  ["repeatEvery":frequency-in-seconds,]  
  ["repeatExpiresAt":expiration-timestamp]  *// the value is to be in milliseconds*  
}

where:

Argument                Description
headers Contains message headers. Headers deliver additional content to subscribers, but also may be referenced by subscribers for message filtering purposes. See the Publish with Headers section for an example. Additionally, see the Conditional Delivery section for information on how to use headers to filter delivered messages.
publishAt Optional property. If present, must be a timestamp when the message should be delivered to subscribers.
releatEvery Optional property. If present, must be a number of seconds defining the frequency of sending the message.
repeatExpiresAt Optional property. If present, must be a timestamp when the repeat publishing of the message must stop.

Response Body

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

In order to obtain message delivery 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

pubsub_api_basic_publish_1

where:

Argument                Description
channel name Name of the channel where a message must be published to.
subtopic name The subtopic of the message allows developers to designate and filter messages by subtopic name. For instance, if a messaging application has a group and a few subgroups, all messages sent to the main group can be marked with this subtopic name which can be used to route messages to the appropriate subgroups depending on the context.
message The contents of the message that must be published to a channel.
headers Message headers is a collection of name/value pairs. A subscriber can set a filter expressed as an SQL "where clause" query (called selector) which Backendless uses to determine whether a message should be delivered to the subscriber. When the query matches the published data in message headers, message is delivered to the corresponding subscriber. For more information see the Conditional Delivery section of this guide.
publish at Must be a Unix Timestamp, which is the number of milliseconds since the Epoch (January 1st, 1970 at UTC).  Note that if you want to specify the number of seconds instead of milliseconds, you must multiply the number by 1000 or add three trailing zeroes to your number (e.g. (1681324179 * 1000) or 1681324179000.
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 status of the message delivery and a unique message identifier:

// Sample object  

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

For examples refer to the following topics: