Topics

Topics are a way to group notifications about a specific entity in your system. You can use them for orders, tickets, posts, documents, interests, etc, depending on what you are building. Let's use GitHub as an example. An example category is comment. Users comment on various kinds of activity - one example being pull requests. The topic in this example is a specific pull request. Therefore, you can create (and fetch) notifications with the topic pull-request-{{id}}.

Creating notifications for a topic

When creating a notification, you can set a topic in the broadcast.topic parameter. A topic must contain less than 256 characters and should not contain spaces. Continuing our Github example, for the pull request with ID 123, the notifications should be created with the topic pull-request-123

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

Fetching notifications for a topic

Topics help with fetching all notifications for a specific entity in your system. For example, you may want to show all notifications about a specific order in your UI. You can use our Rest API or GraphQL endpoint to fetch all notifications for a topic by supplying the topic query param. You can also mark all notifications for a topic read in one API call.