Skip to main content

Topics

Novu offers a simple API providing an easy interface for triggering notifications to multiple subscribers at once. It is called Topics and allows the users to manage their bulk notifications without having to do complex loop implementations. A topic is identified by a custom key that is provided by the user. It will be the identifier used in the Topics API.

warning

The topic key should be unique and can't be changed once chosen. Novu also safe guards for key uniqueness behind the scenes.

Users can also assign a name to a topic. This name doesn't need to be unique and it can be changed using the API. So far, it is for descriptive goals.

A topic would get assigned different subscribers that will receive a notification every time a notification is sent to the topic.

Create a topic​

In order to be able to send a notification to a topic, first the user needs to create one. It can be done like this:

import { Novu } from '@novu/node';

const novu = new Novu(process.env.NOVU_API_KEY);

const result = await novu.topics.create({
  key: 'unique-topic-identifier',
  name: 'descriptive-topic-name',
});

If successful this will return the internal ID generated by Novu and the topic key given by the user.

That topic key can be used to retrieve the whole Topic entity:

import { Novu } from '@novu/node';

const novu = new Novu(process.env.NOVU_API_KEY);

const key = 'unique-topic-identifier';

const result = await novu.topics.get(key);

To rename a topic, this call can be used:

import { Novu } from '@novu/node';

const novu = new Novu(process.env.NOVU_API_KEY);

const topicKey = 'posts:comment:12345';
const topicName = 'Post Comments';

const result = await novu.topics.rename(topicKey, topicName);

This will return the whole Topic information, including the subscribers if having any.

Subscribers management in a topic​

In Subscribers, it is explained how to create subscribers using Novu API. Once created the subscribers that the user wants to assign to the topic, it can be done using the subscriber identifier given to any subscriber. Check the entry Subscriber identifier for more information. Novu Topics API allows to assign the subscribers to the topic like this:

import { Novu } from '@novu/node';

const novu = new Novu(process.env.NOVU_API_KEY);

const topicKey = 'posts:comment:12345';

const response = await novu.topics.addSubscribers(topicKey, {
  subscribers: ['subscriber-id-1', 'subscriber-id-2', ...],
});

This call will return a response in the shape of:

{
    succeeded: ['subscriber-id-1', 'subscriber-id-2', ...],
    failed: {
      notFound: ['subscriber-id-1', 'subscriber-id-2', ...],
    },
}

The field succeeded will return the array of subscriber ids that have been correctly assigned to the topic. The field failed will show up only if there has been any subscriber that couldn't been assigned to the topic. This probably will happen if there is any typo in the subscriber ID given, if the subscriber ID give doesn't belong to the environment and the organization where the topic has been created.

Likewise, a user can remove subscribers assigned to a topic. For that this API call can be used:

import { Novu } from '@novu/node';

const novu = new Novu(process.env.NOVU_API_KEY);

const topicKey = 'posts:comment:12345';

const response = await novu.topics.removeSubscribers(topicKey, {
  subscribers: ['subscriber-id-1', 'subscriber-id-2', ...],
});

Where subscribers will be an array of the subscriber identifiers we want to unassign from the topic. If successful an empty response will be returned.

Sending a notification to a topic​

In the section Quick Start it is explained how to trigger a notification for a single subscriber either by passing the subscribers identifier or by passing the full subscriber information if user wants to skip the identify step. Thanks to the topics feature, now it is possible to trigger a notification to all the subscribers assigned to a topic, which helps to have to avoid to list all the subscriber identifiers in the to field of the notification trigger. To trigger a notification to all the subscribers of a topic, Novu's API allows it by doing this:

const topicKey = 'posts:comment:12345';

await novu.trigger('<REPLACE_WITH_EVENT_NAME_FROM_ADMIN_PANEL>', {
  to: [{ type: 'Topic', topicKey: topicKey }],
  payload: {},
});

As it is shown, the same call used to send a notification to a single subscriber can be used to send the notification to the subscribers of a topic. The topics feature also added the functionality of sending a notification to multiple topics at the same time, a topic and multiple single subscribers or any combination a user might come with. For that, the to field of the notification trigger can take an array that accepts all those possible destination of the notification:

const topicKey = '<TOPIC-KEY-DEFINED-BY-THE-USER>';

await novu.trigger('<REPLACE_WITH_EVENT_NAME_FROM_ADMIN_PANEL>', {
  to: [
    { type: 'Topic', topicKey: topicKey },
    { type: 'Topic', topicKey: 'Another Topic Key' },
  ],
  payload: {},
});

Exclude actor from topic trigger event​

To exclude the actor responsible for the action of a triggered topic event, you must add the subscriberId of that actor when triggering that event.

const topicKey = 'posts:comment:12345';

await novu.trigger('<REPLACE_WITH_EVENT_NAME_FROM_ADMIN_PANEL>', {
  to: [{ type: 'Topic', topicKey: topicKey }],
  payload: {},
  actor: { subscriberId: '<SUBSCRIBER_ID_OF_ACTOR>' },
});

Usecase Example​

User X makes a comment, other users (A, B) who've already commented before should get a notification. So, when triggering the notification on that topic, you would usually want to exclude User X from receiving a notification about their own comment. To do that - you would need to add User X's subscriberId to the trigger event.