Notifications

You can configure your plugin to send notifications (Email, Mobile Push or Browser Push).

Prerequisites#

You must own a plugin and have it installed on a subscription. You can find more information about this topic on the Distribute the Plugin page.
You must also have a Notification Api Key. You can read about acquiring one on the Api Keys page.

Configuration#

To configure a notification for your plugin you have to make some changes in your definition.json file. You have to add a new property called notifications that accepts an array of objects. Each object represents a Plugin Notification Definition. A plugin notification definition consists of the following properties:

Properties		Type	Description
`key`	*required*	`string`	A unique key that we use for identifying this notification definition.
`title`	*required*	`string`	The default title that will show up for users in the notification settings page.
`possibleNotificationTypes`	*required*	`[string]`	The type of notifications your plugin supports. We support any combination of: `"MobilePush", "BrowserPush", "Email"`.
`titleTranslations`	default `null`	`Dictionary<string, string>`	Optional translations for the title. Key represents the language code (ex. `en` or `de`) and value the actual translation in that language.
`description`	default `null`	`string`	Optional description of the notification setting.
`descriptionTranslations`	default `null`	`Dictionary<string, string>`	Optional translations for the description. Comparable to the title translations.

Example#

{
  "pluginId": "MyPlugin",
  // ...
  "notifications": [
    {
      "key": "my-plugin-notif-key-1",
      "title": "My Plugin Notification",
      "description": "You can opt-in for notification about My Plugin.",
      "titleTranslations": {
        "de": "Meine Plugin-Benachrichtigung",
        "ko": "내 플러그인 알림"
      },
      "descriptionTranslations": {
        "de": "Sie können sich für Benachrichtigungen über My Plugin entscheiden.",
        "ko": "내 플러그인에 대한 알림을 수신하도록 선택할 수 있습니다."
      },
      "possibleNotificationTypes": ["BrowserPush", "Email"]
    }
  ]
}

Publishing this definition file should result in a new Notification Setting in the User Notification Settings page.

Send Notification#

In order to send a notification you have to call a specific endpoint on the Reach Api. The endpoint is formed as follows: /plugins/<pluginId>/notifications The pluginId must be the same as specified in the definition.json.

The request is a POST and it must contain the following headers:

Authorization: it should contain the Plugin Notification Api key generated in a previous step
Content-Type: it should be application/json because we expect to get a JSON as the body

The body must contain a JSON object with the following properties:

Properties		Type	Description
`SubscriptionId`	*required*	`string`	The id of the target subscription. The subscription must have this plugin installed or it won't work.
`Title`	*required*	`string`	The title of the notification.
`Content`	*required*	`string`	The content of the notification. Will be ignored in case `ContentHtml` is specified.
`NotificationKey`	*required*	`string`	This key must match the `Key` specified in the definition.json Plugin Notification Definition.
`NotificationTypes`	*required*	`[string]`	The type of the notification you want to send out. We support any combination of: `"MobilePush", "BrowserPush", "Email"`. The values used must be a subset of the PossibleNotificationTypes defined in the definition.json. If a user decided to opt-out they won't receive that type of notification.
`GroupIds`	default `null`	`[string]`	GroupIds or UserIds (or both) must be specified. These will be used to target the recipients of the notifications. To obtain a groupId go the *Groups* section in the *Settings* inside Reach and click on the *Permission assignment* of a group you would like to add. Next copy the groupId from the url.
`UserIds`	default `null`	`[string]`	GroupIds or UserIds (or both) must be specified. These will be used to target the recipients of the notifications. One can find their userId on the *About* page in Reach.
`ContentHtml`	default `null`	`string`	HTML snippet that will replace `Content` if specified.
`Url`	default `null`	`string`	If set will render an `Open in Reach` button navigating to this url.

Example#

{
  "Method": "POST",
  "Headers": {
    "Authorization": "Bearer <Plugin-Notification-Api-Key>",
    "Content-Type": "application/json"
  },
  "Body": {
    "GroupIds": [
      // ...
    ],
    "UserIds": [
      // ...
    ],
    "Title": "Important announcement!",
    "Content": "We won't hold any meetings tomorrow!",
    "NotificationTypes": ["Email", "BrowserPush"],
    "NotificationKey": "my-plugin-notif-key-1",
    "SubscriptionId": "a95de2ad-46bb-41e8-af99-5692132ca350",
    // If specified "Content" will be ignored
    "ContentHtml": "<h1>Important announcement!</h1> <br /> <p>We won't hold any meetings tomorrow!</p>",
    "Url": "https://reach.livetiles.io/"
  }
}

Notifications

Prerequisites#

Configuration#

Example#

Send Notification#

Example#

Email#

Browser Push#