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:

Blocking API

Publishes a message to the default channel.

public MessageStatus Backendless.Messaging.Publish( object message )

Same as above, but publishes into the specified channel.

public MessageStatus Backendless.Messaging.Publish( object message,
                                                    string channelName )

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

public MessageStatus Backendless.Messaging.Publish( object message, 
                                                    PublishOptions publishOptions )

Same as above, but publishes into the specified channel.

public MessageStatus Backendless.Messaging.Publish( object message, 
                                                    string channelName,
                                                    PublishOptions publishOptions )

Publishes a message to the default channel. Message 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 )

Same as above, but publishes into the specified channel.

public MessageStatus Backendless.Messaging.Publish( object message,
                                                    string channelName,
                                                    PublishOptions publishOptions,
                                                    DeliveryOptions deliveryOptions )

Non-Blocking API

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

// Publishes message to "Default" channel.
public MessageStatus Backendless.Messaging.Publish( object message,
                                                    AsyncCallback<MessageStatus> publishResponder )

// Same as above, but published into the specified channel.
public MessageStatus Backendless.Messaging.Publish( object message,
                                                    string channelName,
                                                    AsyncCallback<MessageStatus> publishResponder )

// Publishes message to "Default" channel. Message may have headers and/or subtopic defined in the 
// publishOptions argument.
public MessageStatus Backendless.Messaging.Publish( object message, 
                                                    PublishOptions publishOptions,
                                                    AsyncCallback<MessageStatus> publishResponder )

// Same as above, but published into the specified channel.
public MessageStatus Backendless.Messaging.Publish( object message,
                                                    string channelName, 
                                                    PublishOptions publishOptions,
                                                    AsyncCallback<MessageStatus> publishResponder )

// Publishes message to "Default" channel. Message may have headers and/or subtopic 
// defined in the publishOptions argument. The deliveryOptions argument can be used to: 
// (1) designate the message as "push notification only" or both a push notification 
// and a pub/sub message; (2) publish the message at a later time (delayed publishing); 
// (3) specify that the message should be republished multiple times (repeated publishing).
public MessageStatus Backendless.Messaging.Publish( object message, 
                                                    PublishOptions publishOptions, 
                                                    DeliveryOptions deliveryOptions,
                                                    AsyncCallback<MessageStatus> publishResponder )

// Same as above, but published into the specified channel.
public MessageStatus Backendless.Messaging.Publish( object message,
                                                    string channelName,
                                                    PublishOptions publishOptions,
                                                    DeliveryOptions deliveryOptions,
                                                    AsyncCallback<MessageStatus> publishResponder )

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 Delayed Publish and Repeated Publish sections for examples.
deliveryOptions an instance of DeliveryOptions. When provides 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 a data structure which contains ID of the published message and the status of the publish operation. Available properties in the returned object include:

Status - status of the published message as defined in the BackendlessAPI.Messaging.PublishStatusEnum enumeration.

MessageId - an ID assigned to the message by the backend (the ID is needed to cancel the message).

ErrorMessage - When the message Status is returned as PublishStatusEnum.FAILED, the corresponding error message is available through the ErrorMessage property.

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.