Merge pull request #969 from novuhq/manage-topics-page

Content for the manage topics page

Author: Aviatorscode2

content/docs/platform/subscribers-and-topics/manage-topics.mdx

@@ -0,0 +1,335 @@
+---
+title: 'Manage Topics'
+description: "Learn how to use topics to group subscribers and broadcast notifications to thousands of users with a single API call."
+icon: 'Tags'
+---
+
+Novu provides multiple ways to manage topics, either through the dashboard or the API. Both options give you flexibility depending on whether you prefer a UI-based workflow or direct API integration.
+
+### Create a Topic
+
+Creating a topic defines a new group of subscribers that can later be targeted in workflow triggers. You can create a topic either from the Dashboard or using the API:
+
+#### Create a topic via dashboard
+
+1. Login to the Novu dashboard
+2. Go to **Topics** in the left navigation.
+3. Click the **Create Topic** button.
+4. Provide a unique **Name** and **Topic Key**.
+5. Click on the **Create topic** button.
+
+![Add a topic](/images/manage-subscribers/add-topic.png)
+
+#### Create a topic via API
+
+You can create a new topic using the `topics.create` method.
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
+
+async function run() {
+  const result = await novu.topics.create({
+    key: "task:12345",
+    name: "Task Title",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+Novu also supports on-the-fly topic creation. If you attempt to add subscribers to a topic key that doesn't exist for the selected environment and organization, Novu will automatically create a new topic named `Autogenerated-<TOPIC_KEY>` and assign the subscribers to it.
+
+This auto-generated topic can then be renamed and managed just like any other topic created manually.
+
+### Retrieve a topic
+
+Retrieving a topic allows you to confirm that it exists and view its details, including the name and key.
+
+```ts
+import { Novu } from "@novu/api";
+ 
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
+ 
+async function run() {
+  const result = await novu.topics.get("<value>");
+ 
+  console.log(result);
+}
+
+run();
+```
+
+### Update a topic name
+
+You can update the display name of a topic to better reflect its purpose. The `topicKey` itself is permanent and cannot be modified after the topic is created.
+
+#### Update a topic name via dashboard
+
+1. Log in to the Novu dashboard
+2. From the **Topics** page, click on the topic you want to update
+3. From the Overview tab, update the name of the topic
+4. Click **Save changes** to save.
+
+![Update a topic](/images/manage-subscribers/update-topic.png)
+
+#### Update a topic name via API
+
+Use the `topics.update` method with the topic's key to update the name of a topic
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
+
+async function run() {
+  const result = await novu.topics.update(
+    { name: "Updated Topic Name" },
+    "task:12345" // topicKey
+  );
+
+  console.log(result);
+}
+
+run();
+```
+
+### List all topics
+
+Listing topics lets you see all groups that have been created in the current environment. This is useful for confirming available topic keys and checking which topics exist before triggering workflows.
+
+#### Get list of topics via dashboard
+1. Log in to the Novu dashboard
+2. From the **Topics** page, you will see the list of all topics that have bee created either from the dashboard or using the API.
+
+#### List all topics via API
+Use the `topics.list` method.
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE", });
+
+async function run() {
+  const result = await novu.topics.list({});
+  console.log(result);
+}
+
+run();
+```
+
+### Delete a topic
+
+Deleting a topic permanently removes the grouping, but it does not affect the subscribers themselves. This action is irreversible, so be sure you no longer need the topic before deleting it.
+
+#### Delete a topic via dashboard
+
+1. Log in to the Novu dashboard
+2. From the **Topics** page, click on the topic you want to delete.
+3. Click **Delete topic**.
+4. A modal will appear; click **Delete topic** again to confirm.
+
+![Delete a topic](/images/manage-subscribers/delete-topic.png)
+
+#### Delete a topic via API
+
+Use the `topics.delete` method with the topic's key.
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
+
+async function run() {
+  const result = await novu.topics.delete("task:12345"); // topicKey
+
+  console.log(result);
+}
+
+run();
+```
+
+## Manage topic subscriptions
+
+A topic subscription is a relationship between a subscriber and a topic. Subscriptions track which subscribers belong to which topics.
+
+Subscribers can be added to or removed from a topic at any time, either from the Novu dashboard or through the API.
+
+### Add subscribers to a topic
+
+Adding subscribers to a topic ensures that they receive all notifications sent to that topic. You can add individual subscribers or multiple subscribers at once, depending on your needs.
+
+#### Add subscribers to a topic via dashboard
+
+1. Log in to the Novu dashboard.
+2. From the **Topics** page, select the topic you want to manage.
+3. Go to the **Subscriptions** tab.
+4. Search for and select the subscribers you want to add either using Email, Name, Phone or `SubscriberId`.
+5. Select the subscriber to add them to the topic.
+
+![Add subscribers to a topic](/images/manage-subscribers/add-subscriber-to-topic.gif)
+
+#### Add subscribers to a topic via API
+
+Use the `topics.subscriptions.create()` method to add one or more subscribers to a topic, referencing the topic's key and an array of `subscriberIds`.
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
+
+async function run() {
+  const result = await novu.topics.subscriptions.create("task:12345", {
+    subscriberIds: [
+      "subscriberId1",
+      "subscriberId2",
+    ],
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Remove subscribers from a topic
+
+Removing subscribers from a topic stops them from receiving notifications sent to that topic. The subscribers remain active in Novu but will no longer be part of that specific group.
+
+#### Remove subscribers from a topic via dashboard
+
+1. Log in to the Novu dashboard.
+2. From the **Topics** page, select the topic.
+3. Go to the **Subscriptions** tab.
+4. Locate the subscriber(s) you want to remove.
+5. Click on the delete icon next to the user who you want to remove from the topic.
+6. In the menu that appears, click **Remove**.
+
+![Remove subscribers from a topic](/images/manage-subscribers/remove-subscriber-from-topic.gif)
+
+#### Remove subscribers from a topic via API
+
+You can use the API to remove one or more subscribers from the topic which a single API call by providing their `subscriberIds`.
+
+```ts
+import { Novu } from "@novu/api";
+ 
+const novu = new Novu({
+  secretKey: "YOUR_SECRET_KEY_HERE",
+});
+ 
+async function run() {
+  const result = await novu.topics.subscriptions.delete({
+    subscriberIds: [
+      "subscriberId1",
+      "subscriberId2",
+    ],
+  }, "<value>");
+ 
+  console.log(result);
+}
+ 
+run();
+```
+
+### List subscribers in a topic
+
+You can view all subscribers currently assigned to a specific topic.
+
+#### List subscribers in a topic via dashboard
+
+1. Log in to the Novu dashboard.
+2. From the **Topics** page, select the topic.
+3. Go to the **Subscriptions** tab to see the list of subscribers currently assigned.
+
+![list subscribers in a topic](/images/manage-subscribers/list-subscribers.png)
+
+#### List subscribers in a topic via API
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
+
+async function run() {
+  const result = await novu.topics.subscriptions.list({
+    topicKey: "task:12345",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Check subscriber subscription
+
+You can confirm whether a specific subscriber belongs to a given topic. This is useful when validating membership before triggering workflows or debugging unexpected notification behavior.
+
+#### Check subscriber subscription via dashboard
+
+1. Log in to the Novu dashboard.
+2. From the **Topics** page, select the topic.
+3. Go to the **Subscriptions** tab.
+4. Use the search bar to look up the subscriber. If they are subscribed, they will appear in the list.
+
+![Check subscriber subscription](/images/manage-subscribers/check-subscriber-subscription.gif)
+
+#### Check subscriber subscription via API
+
+```ts
+import { Novu } from "@novu/api";
+
+const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE" });
+
+async function run() {
+  const result = await novu.topics.subscribers.retrieve(
+    "task:12345", // topicKey
+    "subscriber-id-to-check" // subscriberId
+  );
+
+  console.log(result);
+}
+
+run();
+```
+
+## Explore the topics APIs
+
+These are commonly used topics APIs. Explore all topics APIs on topics [API Reference documentation](/api-reference/topics/topic-schema).
+
+<Cards>
+  <Card
+    title="Create a topic API"
+    href="/api-reference/topics/create-a-topic"
+    description="Create a new topic with name and topicKey"
+  />
+  <Card
+    title="Update a topic API"
+    href="/api-reference/topics/update-a-topic"
+    description="Update existing topic using topicKey"
+  />
+  <Card
+    title="Create topic subscription API"
+    href="/api-reference/topics/create-topic-subscriptions"
+    description="Add multiple subscribers into a topic"
+  />
+  <Card
+    title="List topic subscriptions API"
+    href="/api-reference/topics/list-topic-subscriptions"
+    description="List all subscribers present in a single topic"
+  />
+  <Card
+    title="List all topics API"
+    href="/api-reference/topics/list-all-topics"
+    description="List all topics in an environment"
+  />
+  <Card
+    title="Check subscriber subscription API"
+    href="/api-reference/topics/check-topic-subscriber"
+    description="Check if a subscriber is present in a topic"
+  />
+</Cards>