Skip to main content
Version: v5.0

Subscriptions

Overview#

A subscription associates a given device with a group.

Notifications are then sent, based on matching the device transport type with a sender of the same transport type, and templates with the same transport type.

The device user can typically manage their subscription based on the notifications sent to them. For example, for an EMAIL type subscription, the email address owner must first accept notifications by responding to a link in an email. Notifications can include unsubscribe links that the email address owner user can follow.

Subscription properties#

The following properties are supported when creating a subscription:

  • _namespaces: A string array, which must contain a single item, which must match the namespace of the referenced group.
  • _group._id: The ID of the group to which this subscription relates.
  • _device._id: The ID of the device to which this subscription relates.

From get or list subscription requests, the read-only property _status is available. It shows the current status of the subscription, which will be one of the following values:

  • CREATED: The subscription has been created and will automatically transition to either REQUESTED or ACCEPTED, depending on the subscription type and transport type.
  • REQUESTED: Confirmation has been requested from the end user.
  • ACCEPTED: Confirmation has been received from the end user, or the subscription type and transport type did not require confirmation.
  • CANCELLED: The end-user has cancelled the subscription. For example, when a users clicks the cancel link in an email.

Using the Subscription API#

This section lists some useful examples of using the Notification Service API to perform operations with subscriptions.

For a full reference to the Subscription API, refer to the Subscription Rest API page.

Create a subscription#

To create a subscription, refer to the sample code below.

const subscription = await IafNotification.createSubscription({    _namespaces: project._namespaces,    _type: "DEVICE",    _group: {        _id: group.id    },    _device: {        _id: device.id    }}, ctx);

List subscriptions#

To list subscriptions, you must provide a query. The query must include at a minimum, a set of namespaces for which the calling user has READ permission.

The following query properties are supported, which map to the same properties used when creating subscriptions:

  • namespaces
  • device.id
  • group.id

To list all the subscriptions in your project, refer to the sample code below. 

const subscriptions = await IafNotification.listSubscription({    namespaces: project._namespaces}, ctx);

Delete a subscription#

To delete a subscription, refer to the sample code below. 

await IafNotification.deleteSubscription(subscription._id, ctx);