Subscriptions

Learn how to make use of 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.

{
  "notification": {
    "title": "@unamashana please review this PR",
    "recipients": [
      {
        "email": "hana@magicbell.io",
        "external_id": "00001"
      },
      {
        "topic": {
          "subscribers": true
        }
      }
    ],
    "topic": "pull-request-123",
    "category": "comment"
  }
}

How this all works

  1. When a user subscribes to a topic in your app, a subscription record is created with the status subscribed. You can update subscription status using either our REST API or GraphQL API.
  2. Our backend creates the subscription.
  3. Whenever a topic is specified 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.

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
<a href="{{ unsubscribe_url }}">unsubscribe</a>. {% endif %}
When a user unsubscribes from a topic, they will no longer receive notifications for that topic, even if they are a recipient of the notification.