Skip to content

[DO NOT MERGE] Clean up the topics core concept page #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[DO NOT MERGE] Clean up the topics core concept page #889

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bbad8f3
Clean up the topics core concept page
Aviatorscode2 Jun 30, 2025
abdec0d
fix: update topics page
jainpawan21 Jul 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
237 changes: 22 additions & 215 deletions content/docs/platform/concepts/topics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,234 +4,41 @@ description: 'Learn how topics work in Novu and how they help you organize and t
icon: 'Folders'
---

In Novu, a _topic_ is a way to group subscribers under a shared label so that you can broadcast a message to many users with a single workflow trigger. This fan-out mechanism removes the need to manage individual subscriber IDs for each notification, streamlining scenarios like product announcements, feature rollouts, or status updates.
In Novu, a topic represents a collection of subscribers. It is used to trigger a workflow to many subscribers at once. Instead of triggering a workflow for each individual subscriber, you can trigger it once for a topic. Novu automatically sends the message to every subscriber in that topic.

## Topics identifiers
Topics make it easier to model shared audiences. This helps decouple your notification logic from direct user targeting while preserving per-subscriber preferences and personalization.

Each topic is uniquely identified by a topic key, a permanent, internal reference in your system. You can also assign a name to help describe its purpose, for example, "Task Updates" or "Comment Thread Subscribers".
## How topics work in Novu

The `topicKey` must be unique and cannot be changed after creation; Novu enforces this uniqueness behind the scenes. Example: `task:taskId` or `post:postId`.
When a workflow is triggered to a topic:

Common use cases for topics:
- Notifying all members of a specific team or project
- Messaging users who commented on a post
- Updating subscribers to a specific product or feature
- Novu looks up all subscribers currently assigned to that topic.
- A unique workflow execution is created for each subscriber.
- Each subscriber’s preferences, delivery channels, and personalization are still applied individually.

## How topics fit into Novu's model
This means that even when broadcasting to a large group, messages remain tailored and respectful of each recipient’s configuration.

Novu’s notification system is built around workflows, which are triggered for one or more recipients. Topics act as a special type of recipient, representing a group of subscribers instead of an individual.
## Topics are dynamic

When you trigger a workflow using a topic:
- The `to` field accepts the topic’s key.
- Novu looks up all subscribers assigned to the topic.
- A separate workflow event is created for each subscriber.
Topics reflect real-time relationships in your system. You can add or remove subscribers at any time, and a single subscriber can belong to multiple topics simultaneously.

Topics let you target large groups with a single API call, removing the need to loop through subscribers or send multiple workflow triggers.
Examples of dynamic groupings include:
- Users watching a discussion thread
- Members of a temporary support channel
- All users affected by a new feature release

<Callout>Topics don’t replace individual targeting. You can still trigger workflows for specific subscribers or arrays of subscribers when needed.</Callout>
Topics help you model and manage these types of shifting audiences without hardcoding targeting logic.

## Dynamic and decoupled grouping

Once a topic is created, you can assign or remove subscribers at any time. Subscribers don’t need to know they belong to a topic, and it doesn’t affect their personal notification preferences.

Topics are dynamic and reflect real-time states. For example, a topic might include:
- Users who are currently watching a post
- Team members assigned to a project
## Topic identity and structure

This makes topics especially useful for modeling dynamic relationships in your application.
Each topic is uniquely identified by a `topicKey`, a permanent reference defined by your application. While a human-readable name can be added for clarity, the `topicKey` is used programmatically to assign subscribers and trigger workflows.

## Scalability and limits
Topic keys must be unique within an environment and cannot be changed after creation. You can reuse the same topic keys across different environments like staging and production.

Topics are designed for high-volume, high-efficiency use cases:
- Each topic supports up to 100,000 subscribers.
- A separate workflow event is created for each subscriber when a workflow is triggered to the topic
If a topic does not exist when a subscriber is added to it, Novu will create it on the fly, simplifying integration with your application logic.

## Autogenerated topics
## Topics vs. individual targeting

Novu 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.
Topics are an optional abstraction. You can still target specific subscribers directly when needed. The benefit of topics lies in simplifying group delivery for use cases where the audience changes over time or is not known in advance.


<Callout type="info">
Topics can be managed from [Novu dashboard](https://dashboard.novu.co/topics) or using [Topics APIs](/api-reference/topics/topic-schema)
</Callout>

## Trigger workflow

As mentioned above, a workflow can be triggered to a topic in the same way as it is triggered to subscribers.

### To a single topic

To trigger a workflow to a topic, use `to` field with type `Topic` and topicKey.

<Tabs items={["Node.js", "cURL"]}>
<Tab value="Node.js">
```ts
import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
to: { type: "Topic", topicKey: "topic_key" },
workflowId: "workflow_identifier",
});
```
</Tab>
<Tab value="cURL">
```bash
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
"name": "workflow_identifier",
"to": {
"type": "Topic",
"topicKey": "topic_key"
}
}'
```
</Tab>
</Tabs>

### To multiple topics

`to` field also accepts array of topics. This is useful when you want to trigger a workflow to multiple topics at once.

<Tabs items={["Node.js", "cURL"]}>
<Tab value="Node.js">
```ts
import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
to: [
{ type: "Topic", topicKey: "topic_key_1" },
{ type: "Topic", topicKey: "topic_key_2" }
],
workflowId: "workflow_identifier",
});
```
</Tab>
<Tab value="cURL">
```bash
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
"name": "workflow_identifier",
"to": [
{
"type": "Topic",
"topicKey": "topic_key_1"
},
{
"type": "Topic",
"topicKey": "topic_key_2"
}
]
}'
```
</Tab>
</Tabs>

### Exclude actor

When a workflow is triggered to a topic, notification is sent to all subscribers present in the topic. However, you can exclude a specific subscriber from receiving the notification by using the `actor` field. Here actor is the subscriberId of the subscriber you want to exclude.

<Tabs items={["Node.js", "cURL"]}>
<Tab value="Node.js">
```ts
import { Novu } from "@novu/api"

const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });

await novu.trigger({
to: [{ type: "Topic", topicKey: "topic_key_1" }],
workflowId: "workflow_identifier",
actor: "actor_subscriber_Id"
});
```
</Tab>
<Tab value="cURL">
```bash
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
"name": "workflow_identifier",
"to": [
{
"type": "Topic",
"topicKey": "topic_key_1"
}
],
"actor": "actor_subscriber_Id"
}'
```
</Tab>
</Tabs>


## Explore the topics APIs

These are commonly used topics APIs. Explore all topics APIs on topics [api reference page](/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>

## Frequently asked questions

Below are some of the most frequently asked questions about topics:

### Do topics override subscriber preferences?

No. Topics only define delivery groups. Each subscriber’s individual notification preferences remain intact.

### Is a topic like a mailing list?

Conceptually, yes. Topics group users to receive shared messages. However, topics are more dynamic and integrated into your application logic.

### Can a subscriber belong to multiple topics?

Yes. Subscribers can be members of any number of topics. This allows overlapping targeting strategies (for example, `task-updates`, `project-X`, and `admin-notifications`).

### Can I reuse the same topic key across environments?

Topic keys must be unique within each [environment](/platform/concepts/environments). You can reuse the same key (for example, `feature-release`) in different environments like staging and production.

### What happens if I trigger a workflow to a topic with no subscribers?

The workflow is processed, but no notifications are delivered and, hence, this trigger is not counted for billing.
They complement, not replace, subscriber-level targeting, giving you flexibility and control over how notifications are sent at scale.