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:

API Specification

Publishes a message to the specified channel.

- (void)publishWithChannelName:(NSString * _Nonnull)channelName message:(id _Nonnull)message responseHandler:^(MessageStatus * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func publish(channelName: String, message: Any, responseHandler: ((MessageStatus) -> Void)!, errorHandler: ((Fault) -> Void)!)

Publishes a message to the specified channel with publish options. Publish options allow to set message headers, publisher ID and subtopic.

- (void)publishWithChannelName:(NSString * _Nonnull)channelName message:(id _Nonnull)message publishOptions:(PublishOptions * _Nonnull)publishOptions responseHandler:^(MessageStatus * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func publish(channelName: String, message: Any, publishOptions: PublishOptions, responseHandler: ((MessageStatus) -> Void)!, errorHandler: ((Fault) -> Void)!)

Publishes a message to the specified channel with publish and delivery options. Publish options allow to set message headers, publisher ID and subtopic. Delivery options 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).
- (void)publishWithChannelName:(NSString * _Nonnull)channelName message:(id _Nonnull)message publishOptions:(PublishOptions * _Nonnull)publishOptions deliveryOptions:(DeliveryOptions * _Nonnull)deliveryOptions responseHandler:^(MessageStatus * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func publish(channelName: String, message: Any, publishOptions: PublishOptions, deliveryOptions: DeliveryOptions, responseHandler: ((MessageStatus) -> Void)!, errorHandler: ((Fault) -> Void)!)

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 a collection of headers. See the Delayed Publish and Repeated Publish sections for examples.
deliveryOptions an instance of DeliveryOptions. When provided may specify options for message delivery such as: deliver only as a push notification (as opposed to push notification and a pub/sub message), delayed delivery or repeated delivery. See the Delayed Publish and Repeated Publish sections for examples.

Return value

MessageStatus- a data structure which contains message ID and message status:

@interface MessageStatus : NSObject

@property (nonatomic, copy) NSString *messageId;
@property (nonatomic, copy) NSString * status;
@property (nonatomic, copy) NSString *errorMessage;

@end
@objcMembers open class MessageStatus: NSObject {

    open var messageId: String?
    open var status: String?
    open var errorMessage: String?
}

Supported message statuses are:

  • PUBLISHED - message has been successfully published
  • SCHEDULED - message has been put into queue for delivery, it will be published immediately as soon as computing resources become available within Backendless
  • FAILED - message publishing failed. See the errorMessage property in MessageStatus for details.

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.