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:

Basic message publish
Publishing with headers - can be used for conditional delivery
Delayed publishing
Repeated publishing

Backendless.Messaging.publish( channelName, 
                               message, 
                               publishOptions, 
                               deliveryOptions )
 .then( function( response ) {
  })
 .catch( function( error ) {
  });

where:

Argument	Description
`channelName`	Name of the channel to publish the message to. If the channel does not exist, Backendless automatically creates it.
`message`	Object to publish. Can be a primitive value, an array or a complex type.
`publishOptions`	Optional argument. An instance of the `Backendless.PublishOptions` class. Contains publisher ID, and message headers. See the Publish with Headers section for examples.
`deliveryOptions`	Optional argument. An instance of the `Backendless.DeliveryOptions` class. May specify message delivery policy, timestamp (in milliseconds) for publishing at the specified time i the future, interval for repeated publishing. See the Delayed Publish and Repeated Publish sections for examples.

Return value¶

A JavaScript object containing message ID and the status of the publishing operation. In order to obtain message delivery status, use the Get Message Status API with the messageId value returned by this API.

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

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

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: