Notifications (Api 4.0+)

The following section will explain how to setup notifications for your users in the notification center of Touch Portal.

Sending a notification to Touch Portal (Api 4.0+)

As a plug-in developer you can alert your users within Touch Portal for certain events. This system should only be used for important messages that the user has to act on. Examples are new updates for the plugin or changing settings like credentials.

To trigger a notification you should send a message to Touch Portal with the following structure:

{
  "type":"showNotification",
  "notificationId":"id of the notification",
  "title":"The title of your notification",
  "msg":"The body text of your notification",
  "options": [
    {
      "id":"option id",
      "title":"option title"
    },
    {
      "id":"option id",
      "title":"option title"
    }
  ]
}


Rules of notifications

You are only allowed to send user critical notifications to help them on their way. Advertisements, donation request and all other non-essential messages are not allowed and may result in your plug-in be blacklisted from the notification center.



Notification message details

Attribute Type Mandatory From version Description
notificationId Text Yes 4.0 This is the id of this notification. Every notification with a unique id will have its own entry in the notification center. The same id should be used for the same kind of message to the user. For example; if you want to show a notification to update to a specific version, use the same id each time you send this notification. This will just show the one notification to the user.
title Text Yes 4.0 This is the title of the notification.
msg Text Yes 4.0 This is the message that is shown in the notification to the user.
options Collection Yes 4.0 This is the collection of options to go with your notification. When a user clicks on the action it will be send to the plugin. The plug-in then can react on the choice the user made. Usually this will contain only one option such as an "Update" or "More Info" option. At least one option is required.

Notification option details

Attribute Type Mandatory From version Description
id Text Yes 4.0 This is the id of the notification option. This id will be send back to the plug-in if the user selects the option.
title Text Yes 4.0 This is the title of the notification option.

Communication from Touch Portal (Api 4.0+)

Touch Portal will send a message when a user clicks on a notification action. When they do the notification is also marked as read/handled. Below is the structure of the message the plug-in receives from Touch Portal.

{
  "type":"notificationOptionClicked",
  "notificationId":"id of the notification",
  "optionId":"id of the option"
}