Subscriptions

Subscriptions allow users to subscribe to and unsubscribe from specific topics. Continuing with our GitHub example:

1. Jane would like to receive all notifications related to comments on pull requests.
2. Jane subscribes to the topic pull-request.
3. When a notification is sent in MagicBell with any topic for which pull-request is a substring (e.g., pull-request-1234 or pull-request.1234) of the topic, Jane will be notified.
4. Jane then sees that pull-request-1234 is being handled by one of their peers and, due to the constant back and forth, decides they no longer want to be notified about this.
5. Jane unsubscribes from pull-request-1234 and stops receiving notifications for that pull request, but will continue to be notified of others.

Creating notifications for subscribers

The { "topic": { "subscribers": true } } recipient can be used to send notifications to subscribers. It can be used on its own or along with other recipients. If this recipient is not specified, the notification will only be sent to the designated recipients.

{
  "broadcast": {
    "title": "@unamashana please review this PR",
    "recipients": [
      {
        "email": "[email protected]",
        "external_id": "00001"
      },
      {
        "topic": {
          "subscribers": true
        }
      }
    ],
    "topic": "pull-request-123",
    "category": "comment"
  }
}

How users are subscribed

Users are automatically subscribed to the combination of topic and category when they are specified as a recipient on a notification. If no category is provided for the notification the subscription record will match all categories. As an alternative, users can be manually subscribed to a topic/category with the following process:

1. When a user want to subscribes to a topic, the app should send a POST request to the subscriptions endpoint.
2. A subscription record is then created with the status subscribed. You can unsubscribe and resubscribe the user using the REST API.
3. Whenever a matching category & topic is used in a notification, the user will receive the notification.

How users can unsubscribe

When sending a notification you can use the {{ unsubscribe_url }} merge tag to generate a URL for the specific recipient and the notification's topic — this can be used in templates, email layout, and in notification content. When the unsubscribe link requires the category as well use {{ unsubscribe_url | category: "current" }}.

As we don't generate unsubscribe URLs when a topic isn't specified for a notification, consider using control flow to avoid an empty object being rendered in your notification:

LIQUID
{% if unsubscribe_url != "" %} Click here to
unsubscribe. {% endif %}