Skip to content

Commit bbad8f3

Browse files
Aviatorscode2Aviatorscode2
committed
Clean up the topics core concept page
1 parent bdcf848 commit bbad8f3

File tree

1 file changed

+22
-215
lines changed

1 file changed

+22
-215
lines changed

‎content/docs/platform/concepts/topics.mdx‎

Lines changed: 22 additions & 215 deletions
Original file line numberDiff line numberDiff line change
@@ -4,234 +4,41 @@ description: 'Learn how topics work in Novu and how they help you organize and t
44
icon: 'Folders'
55
---
66

7-
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.
7+
In Novu, a topic represents a collection of subscribers. It is used to deliver the same message 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.
88

9-
## Topics identifiers
9+
Topics make it easier to model shared audiences. They help decouple your notification logic from direct user targeting while preserving per-subscriber preferences and personalization.
1010

11-
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".
11+
## How topics work in Novu
1212

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

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

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

22-
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.
21+
## Topics are dynamic
2322

24-
When you trigger a workflow using a topic:
25-
- The `to` field accepts the topic’s key.
26-
- Novu looks up all subscribers assigned to the topic.
27-
- A separate workflow event is created for each subscriber.
23+
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.
2824

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

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

33-
## Dynamic and decoupled grouping
34-
35-
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.
36-
37-
Topics are dynamic and reflect real-time states. For example, a topic might include:
38-
- Users who are currently watching a post
39-
- Team members assigned to a project
32+
## Topic identity and structure
4033

41-
This makes topics especially useful for modeling dynamic relationships in your application.
34+
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.
4235

43-
## Scalability and limits
36+
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.
4437

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

49-
## Autogenerated topics
40+
## Topics vs. individual targeting
5041

51-
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.
42+
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.
5243

53-
54-
<Callout type="info">
55-
Topics can be managed from [Novu dashboard](https://dashboard.novu.co/topics) or using [Topics APIs](/api-reference/topics/topic-schema)
56-
</Callout>
57-
58-
## Trigger workflow
59-
60-
As mentioned above, a workflow can be triggered to a topic in the same way as it is triggered to subscribers.
61-
62-
### To a single topic
63-
64-
To trigger a workflow to a topic, use `to` field with type `Topic` and topicKey.
65-
66-
<Tabs items={["Node.js", "cURL"]}>
67-
<Tab value="Node.js">
68-
```ts
69-
import { Novu } from "@novu/api"
70-
71-
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
72-
73-
await novu.trigger({
74-
to: { type: "Topic", topicKey: "topic_key" },
75-
workflowId: "workflow_identifier",
76-
});
77-
```
78-
</Tab>
79-
<Tab value="cURL">
80-
```bash
81-
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
82-
-H 'Content-Type: application/json' \
83-
-H 'Accept: application/json' \
84-
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
85-
-d '{
86-
"name": "workflow_identifier",
87-
"to": {
88-
"type": "Topic",
89-
"topicKey": "topic_key"
90-
}
91-
}'
92-
```
93-
</Tab>
94-
</Tabs>
95-
96-
### To multiple topics
97-
98-
`to` field also accepts array of topics. This is useful when you want to trigger a workflow to multiple topics at once.
99-
100-
<Tabs items={["Node.js", "cURL"]}>
101-
<Tab value="Node.js">
102-
```ts
103-
import { Novu } from "@novu/api"
104-
105-
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
106-
107-
await novu.trigger({
108-
to: [
109-
{ type: "Topic", topicKey: "topic_key_1" },
110-
{ type: "Topic", topicKey: "topic_key_2" }
111-
],
112-
workflowId: "workflow_identifier",
113-
});
114-
```
115-
</Tab>
116-
<Tab value="cURL">
117-
```bash
118-
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
119-
-H 'Content-Type: application/json' \
120-
-H 'Accept: application/json' \
121-
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
122-
-d '{
123-
"name": "workflow_identifier",
124-
"to": [
125-
{
126-
"type": "Topic",
127-
"topicKey": "topic_key_1"
128-
},
129-
{
130-
"type": "Topic",
131-
"topicKey": "topic_key_2"
132-
}
133-
]
134-
}'
135-
```
136-
</Tab>
137-
</Tabs>
138-
139-
### Exclude actor
140-
141-
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.
142-
143-
<Tabs items={["Node.js", "cURL"]}>
144-
<Tab value="Node.js">
145-
```ts
146-
import { Novu } from "@novu/api"
147-
148-
const novu = new Novu({ secretKey: "<YOUR_SECRET_KEY_HERE>", });
149-
150-
await novu.trigger({
151-
to: [{ type: "Topic", topicKey: "topic_key_1" }],
152-
workflowId: "workflow_identifier",
153-
actor: "actor_subscriber_Id"
154-
});
155-
```
156-
</Tab>
157-
<Tab value="cURL">
158-
```bash
159-
curl -L -g -X POST 'https://api.novu.co/v1/events/trigger' \
160-
-H 'Content-Type: application/json' \
161-
-H 'Accept: application/json' \
162-
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
163-
-d '{
164-
"name": "workflow_identifier",
165-
"to": [
166-
{
167-
"type": "Topic",
168-
"topicKey": "topic_key_1"
169-
}
170-
],
171-
"actor": "actor_subscriber_Id"
172-
}'
173-
```
174-
</Tab>
175-
</Tabs>
176-
177-
178-
## Explore the topics APIs
179-
180-
These are commonly used topics APIs. Explore all topics APIs on topics [api reference page](/api-reference/topics/topic-schema).
181-
182-
<Cards>
183-
<Card
184-
title="Create a topic API"
185-
href="/api-reference/topics/create-a-topic"
186-
description="Create a new topic with name and topicKey"
187-
/>
188-
<Card
189-
title="Update a topic API"
190-
href="/api-reference/topics/update-a-topic"
191-
description="Update existing topic using topicKey"
192-
/>
193-
<Card
194-
title="Create topic subscription API"
195-
href="/api-reference/topics/create-topic-subscriptions"
196-
description="Add multiple subscribers into a topic"
197-
/>
198-
<Card
199-
title="List topic subscriptions API"
200-
href="/api-reference/topics/list-topic-subscriptions"
201-
description="List all subscribers present in a single topic"
202-
/>
203-
<Card
204-
title="List all topics API"
205-
href="/api-reference/topics/list-all-topics"
206-
description="List all topics in an environment"
207-
/>
208-
<Card
209-
title="Check subscriber subscription API"
210-
href="/api-reference/topics/check-topic-subscriber"
211-
description="Check if a subscriber is present in a topic"
212-
/>
213-
</Cards>
214-
215-
## Frequently asked questions
216-
217-
Below are some of the most frequently asked questions about topics:
218-
219-
### Do topics override subscriber preferences?
220-
221-
No. Topics only define delivery groups. Each subscriber’s individual notification preferences remain intact.
222-
223-
### Is a topic like a mailing list?
224-
225-
Conceptually, yes. Topics group users to receive shared messages. However, topics are more dynamic and integrated into your application logic.
226-
227-
### Can a subscriber belong to multiple topics?
228-
229-
Yes. Subscribers can be members of any number of topics. This allows overlapping targeting strategies (for example, `task-updates`, `project-X`, and `admin-notifications`).
230-
231-
### Can I reuse the same topic key across environments?
232-
233-
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.
234-
235-
### What happens if I trigger a workflow to a topic with no subscribers?
236-
237-
The workflow is processed, but no notifications are delivered and, hence, this trigger is not counted for billing.
44+
They complement, not replace, subscriber-level targeting, giving you flexibility and control over how notifications are sent at scale.

0 commit comments

Comments
 (0)