Push with API¶

Message publishing API supports the following scenarios:

Scenarios	Description
`Push notification from a Push Template`	This approach is the simplest and yet provides the most flexibility when it comes to identifying a dynamic audience of who will be receiving the notification, creating custom, personalized content for each recipient and configuring numerous visual and audible effects. To send out push notifications for a Push Template using the API, make sure to start with defining a Push Template first. For more information see the About Push Templates section of the guide. API Example.
`Basic push notification`	It is the simplest form of a push notification. It is sent to a channel and all devices registered with the channel will be receiving the notification. The notification message must contain headers which control the appearance of the notification on the devices. API Example.
`Push notification delivered to devices grouped by the OS`	With this type delivery, a notification is sent to all devices of a specific operating system (or a combination of). This includes delivery to Android, iOS or both. API Example.
`Push notification delivered to specific devices`	This delivery type allows push notification delivery to individual devices. API Example
`Delayed publishing`	For all scenarios described above a push notification request can be configured to be executed at a later time. API Example.

Blocking API¶

Publishes push notification to the "Default" channel. Headers must be added to the publishOptions argument.

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

Same as above, but published into the specified channel.

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

Publishes push notification to the "Default" channel. Headers must be added to the publishOptions argument. Delivery options can be used to:

Designate the message as "push notification only" or both a push notification and a pub/sub message.
Singlecast publishing - set a list of devices which should be receiving the notification.
Broadcast publishing - identify operating systems of the registered devices which should be receiving the notification.
Publish the message at a later time (delayed publishing).
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 published 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 push notification to the "Default" channel. Headers must be added to 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 push notification to the "Default" channel. Headers must be added to the publishOptions argument.
// With the presence of the deliveryOptions argument, the push notification can be:
// (1) published as a singlecast - targeting specific devices, (2) published with a delay.
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 notification 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.
`deliveryOptions`	An instance of `DeliveryOptions`. When provides may specify options for message delivery such as: deliver to specific devices (or devices grouped by the operating system), delayed delivery or repeated delivery.

Return value¶

Argument	Description
`MessageStatus`	A data structure which contains ID of the published message and the status of the publish operation:

namespace BackendlessAPI.Messaging
{
  public class MessageStatus
  {
    public PublishStatusEnum Status { get; }
    public string MessageId { get; }
    public string ErrorMessage { get; }
  }
}

Supported message statuses are:

namespace BackendlessAPI.Messaging
{
  public enum PublishStatusEnum
  {
    FAILED,
    PUBLISHED,
    SCHEDULED,
    CANCELLED
  }
}

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.

Codeless Reference¶

push_push_with_api_1

where:

Argument	Description
`channel name`	Name of the channel where a message must be published to.
`device ids`	Must be a list containing unique identifiers of the devices that will receive a push notification.
`message`	The contents of the message that must be published to a channel.
`Android ticker text`	Sets the text of the ticker showing up at the top of a device's screen when the device receives the notification.
`Android notification title`	Sets the title of the notification as it is visible in the Android Notification Center
`Android notification text`	Sets the message of the notification which appears under `android-content-title` in the Android Notification Center.
`iOS alert message`	Sets the text of the alert message. If the header is not present and the published notification targets the iOS devices, Backendless sets the header to the value of the "message" argument.
`iOS badge`	Sets the value to update the badge with.
`headers`	Headers control the content and appearance of the push notification on the devices.
`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 following parameters:

// Sample object  

{  
    "messageId":"message:FCBD8BF1-A45D-4564-B449-3C91D4896987",  
    "status":"published",  
    "errorMessage":null  
}

where:

Argument	Description
`messageId`	ID of the message for which the publishing status is retrieved.
`status`	Can be one of the following values: `FAILED`, `PUBLISHED`, `SCHEDULED`, `CANCELLED`, `UNKNOWN`
`errorMessage`	Contains a detailed error message when `status` is `"failed"`.

The example below publishes the message to the "default" channel. This message is delivered only to Android devices, since no values were set for iOS properties.

push_push_with_api_2