diff --git a/concepts/topics.mdx b/concepts/topics.mdx index 5f484cfc..548cd586 100644 --- a/concepts/topics.mdx +++ b/concepts/topics.mdx @@ -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: @@ -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(""); - -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. - -Topic Key can not be changed - ## 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 @@ -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-` 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(""); - -const externalSubscriberId = "external-subscriber-id-1"; -const topicKey = "posts:comment:12345"; - -const response = await novu.topics.getSubscriber( - topicKey, - externalSubscriberId -); -``` - - - 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. - - -## 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(""); - -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(""); - -const key = "unique-topic-identifier"; - -const result = await novu.topics.delete(key); -``` - - - 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. - - ## 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. @@ -183,22 +108,6 @@ await novu.trigger("", { }); ``` -## Trigger workflow to multiple topics - -Workflow can be triggered to multiple subscribers by using an array of topics. - -```typescript -const topicKey = ""; - -await novu.trigger("", { - 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. @@ -213,10 +122,6 @@ await novu.trigger("", { }); ``` -## 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