Skip to content

Commit

Permalink
refactor: topics page
Browse files Browse the repository at this point in the history
  • Loading branch information
@scopsy
scopsy committed Nov 4, 2024
1 parent 7fa599c commit 4a80d0f
Showing 1 changed file with 7 additions and 102 deletions.
109 changes: 7 additions & 102 deletions concepts/topics.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,13 @@ Users can also assign a name to a topic. This name doesn't need to be unique and

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

## Common usecases

- Send to all users who have commented on a post.
- Send to all users who subscribed to task updates.
- Send an update to all tenant members
- Other use cases that require sending a notification to a group of subscribers around a specific structure

## 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:
Expand Down Expand Up @@ -42,25 +49,6 @@ const key = "unique-topic-identifier";
const result = await novu.topics.get(key);
```

## Rename a topic

Descriptive name given during creation of topic can be changed later. This can be done like this:

```typescript
import { Novu } from "@novu/node";

const novu = new Novu("<NOVU_SECRET_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.

<Note>Topic Key can not be changed</Note>

## Add subscribers to a topic

Adding subscribers to the topic is the main usecase of topic. A topic is like a group of subscribers. A notification can be sent to all subscribers of a topic at once
Expand Down Expand Up @@ -105,71 +93,8 @@ The field `succeeded` will return the array of subscriber ids that have been c
To facilitate flows we allow to create a topic on the fly when adding subscribers.

If the topic key used does not exist for the selected environment and organization, Novu will create a new topic with name `Autogenerated-<TOPIC_KEY>` and the subscribers will be assigned to this newly created topic.

After that, that topic created on the fly can be managed in the same ways as the ones created in the normal way.

## Verify if subscriberId belongs to a topic

There would be times when it would be needed to verify if a certain subscriber belongs to a topic in order to decide what to do with that subscriber. The API call to achieve that is the following:

```typescript
import { Novu } from "@novu/node";

const novu = new Novu("<NOVU_SECRET_KEY>");

const externalSubscriberId = "external-subscriber-id-1";
const topicKey = "posts:comment:12345";

const response = await novu.topics.getSubscriber(
topicKey,
externalSubscriberId
);
```

<Note>
The subscriberId to use in this API call is the one used as subscriber
identifier. The choice was made to make easier for the user to use this
without making extra calls to Novu.
</Note>

## Remove a subscriber from a topic

A single or group of subscribers can be removed from an existing topic.

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

const novu = new Novu("<NOVU_SECRET_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 subscriberIds we want to remove from the topic. If successful an empty response will be returned.

## Delete a topic

An existing topic can be deleted using topic-key as topic-key is the unique identifier for a topic.

```typescript
import { Novu } from "@novu/node";

const novu = new Novu("<NOVU_SECRET_KEY>");

const key = "unique-topic-identifier";

const result = await novu.topics.delete(key);
```

<Warning>
A topic can only be deleted if it doesn't have any subscriber added. When
trying to delete a topic with subscribers a conflict error will be returned.
This is done to prevent accidental topic deletions.
</Warning>

## Trigger workflow to a topic

A workflow can be triggered to a single subscriber and an array of subscribers. While doing so, one need to send subscriberIds in `to` field. In case of trigger, we have already stored subscriberIds in a topic, so a topic key can be used to trigger a workflow. Workflow will be triggered to all subscribers in the topic.
Expand All @@ -183,22 +108,6 @@ await novu.trigger("<WORKFLOW_TRIGGER_IDENTIFIER>", {
});
```

## Trigger workflow to multiple topics

Workflow can be triggered to multiple subscribers by using an array of topics.

```typescript
const topicKey = "<TOPIC-KEY-DEFINED-BY-THE-USER>";

await novu.trigger("<WORKFLOW_TRIGGER_IDENTIFIER>", {
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.
Expand All @@ -213,10 +122,6 @@ await novu.trigger("<WORKFLOW_TRIGGER_IDENTIFIER>", {
});
```

## 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.

## API

<CardGroup cols={3}>
Expand Down

0 comments on commit 4a80d0f

Please sign in to comment.