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
API Specification¶
Methods¶
Publishes a message to the default
channel.
Future<MessageStatus> Backendless.messaging.publish(Object message);
Same as above, but publishes to the specified channel.
Future<MessageStatus> Backendless.messaging.publish(Object message, {String channelName});
Publishes a message to the default
channel. May have headers and/or subtopic defined in the publishOptions
argument.
Future<MessageStatus> Backendless.messaging.publish(Object message, {PublishOptions publishOptions});
Same as above, but publishes to the specified channel.
Future<MessageStatus> Backendless.messaging.publish(Object message, {String channelName, PublishOptions publishOptions});
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:
- Publish the message at a later time (delayed publishing).
- Specify that the message should be republished multiple times (repeated publishing).
Future<MessageStatus> Backendless.messaging.publish(Object message, {PublishOptions publishOptions, DeliveryOptions deliveryOptions});
Same as above, but publishes to the specified channel.
Future<MessageStatus> Backendless.messaging.publish( Object message, {String channelName, PublishOptions publishOptions, DeliveryOptions deliveryOptions});
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. |