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

Blocking API

Publishes a message to the default channel.

public MessageStatus Backendless.Messaging.publish( Object message ) 
                                                    throws BackendlessException

Same as above, but publishes to the specified channel.

public MessageStatus Backendless.Messaging.publish( String channelName, 
                                                    Object message ) 
                                                    throws BackendlessException

Publishes a message to the default channel. May have headers and/or subtopic defined in the publishOptions argument.

public MessageStatus Backendless.Messaging.publish( Object message, 
                                                    PublishOptions publishOptions ) 
                                                    throws BackendlessException

Same as above, but publishes to the specified channel.

public MessageStatus Backendless.Messaging.publish( String channelName, 
                                                    Object message, 
                                                    PublishOptions publishOptions ) 
                                                    throws BackendlessException

Publishes a message to the default channel. May have headers and/or subtopic defined in the publishOptions argument. The deliveryOptions argument can be used to:

1. Publish the message at a later time (delayed publishing).
2. Specify that the message should be republished multiple times (repeated publishing).

public MessageStatus Backendless.Messaging.publish( Object message, 
                                                    PublishOptions publishOptions, 
                                                    DeliveryOptions deliveryOptions )
                                                    throws BackendlessException

Same as above, but publishes to the specified channel.

public MessageStatus Backendless.Messaging.publish( String channelName, 
                                                    Object message, 
                                                    PublishOptions publishOptions, 
                                                    DeliveryOptions deliveryOptions ) 
                                                    throws BackendlessException

Non-Blocking API

The same set of methods is available for the non-blocking invocation. The difference in the method signatures is the AsyncCallback<MessageStatus> argument:

// Publishes a message to the default channel:
public void Backendless.Messaging.publish( Object message, 
                                           AsyncCallback<MessageStatus> responder )

// Same as above, but publishes to the specified channel:
public void Backendless.Messaging.publish( String channelName, 
                                           Object message, 
                                           AsyncCallback<MessageStatus> responder )

// Publishes a message to the default channel. 
// May have headers and/or subtopic defined in the publishOptions argument.
public void Backendless.Messaging.publish( Object message, 
                                           PublishOptions publishOptions, 
                                           AsyncCallback<MessageStatus> responder )

// Same as above, but publishes to the specified channel:
public void Backendless.Messaging.publish( String channelName, 
                                           Object message, 
                                           PublishOptions publishOptions, 
                                           AsyncCallback<MessageStatus> responder )

// Publishes a message to the default channel. 
// May have headers and/or subtopic defined in the publishOptions argument. 
// The deliveryOptions argument can be used to:
//    1. Publish the message at a later time (delayed publishing)
//    2. Specify that the message should be republished multiple times (repeated publishing):
public void Backendless.Messaging.publish( Object message, 
                                           PublishOptions publishOptions, 
                                           DeliveryOptions deliveryOptions, 
                                           AsyncCallback<MessageStatus> responder )

// Same as above, but publishes to the specified channel:
public void Backendless.Messaging.publish( String channelName, 
                                           Object message, 
                                           PublishOptions publishOptions, 
                                           DeliveryOptions deliveryOptions, 
                                           AsyncCallback<MessageStatus> responder )

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. The object can be of any data type - a primitive value, String, Date, a  user-defined complex type, a collection or an array of these types.
publishOptions	An instance of PublishOptions. When provided may contain publisher ID (an arbitrary, application-specific string value identifying the publisher), subtopic value and/or a collection of headers. See the Publish with Headers section for examples.
deliveryOptions	An instance of DeliveryOptions. When provided may specify options for message delivery such as: deliver as a push notification, delayed delivery or repeated delivery. See the Delayed Publish and Repeated Publish sections for examples.

Return value

Argument	Description
MessageStatus	An object which contains ID of the published message. Use the getMessageId() method to get the ID assigned to the message by the backend (the ID is needed to check the message publishing  status or cancel the message).

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

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:

• Basic message publish
• Publishing with headers
• Delayed publishing