Broadcasts

Broadcasts let you send notifications to all users who care about a specific topic. Users subscribe to topics they want to follow, and when you broadcast to that topic, everyone subscribed gets notified automatically.

What are Broadcasts?

A broadcast is a notification sent to a topic. Instead of specifying individual recipients, you send to a topic, and Notiflows delivers the message to everyone subscribed to that topic. It's pub-sub for notifications.

Think of broadcasts as sending an announcement to a channel or group. You don't manage the member list—users subscribe themselves, and you just broadcast to the topic.

Topics

Topics are lightweight identifiers that represent things users might want to follow in your app. A topic is just a string—no complex setup, no hierarchies.

Real-world topic examples:

thread-feature-requests - A discussion thread about feature requests
task-homepage-redesign - Updates on a specific task
pr-auth-refactor - Comments and changes on a pull request
project-mobile-app - Updates about the mobile app project
team-engineering - Engineering team announcements
issue-login-bug - Activity on a specific issue

Topics should map naturally to resources and concepts in your application. If users can "follow" something in your app, that's a good candidate for a topic.

How Broadcasts Work

1. Users Subscribe

When users want to follow something, they subscribe to the topic. This could happen when they:

Join a discussion thread
Get assigned to a task
Watch a pull request
Opt into team updates
Follow a project

2. You Broadcast

When something happens that subscribers should know about, trigger a notiflow for that topic:

await notiflows.trigger({
  notiflow: 'comment-added',
  topic: 'thread-feature-requests',
  data: {
    comment: 'I agree, we should prioritize this',
    author: 'Sarah'
  }
})

3. Automatic Delivery

Notiflows finds all users subscribed to thread-feature-requests and sends them the notification. Could be 3 users, could be 3,000—same API call.

4. Users Unsubscribe

Users can unsubscribe anytime. Once unsubscribed, they won't receive future broadcasts to that topic. They can resubscribe later if they change their mind.

Broadcast Use Cases

Discussion Threads

Let users subscribe to threads they participate in or want to follow. When someone comments, broadcast to the thread topic so all subscribers get notified.

Task and Issue Tracking

When users are assigned to tasks or watching issues, subscribe them to those topics. Broadcast updates, status changes, and comments to keep everyone in the loop.

Project Updates

Create topics for projects or teams. Users subscribe to projects they're involved in, and you broadcast important updates to those topics.

Document Collaboration

Subscribe users to documents they're editing or reviewing. Broadcast when someone comments, makes changes, or mentions them.

Pull Request Activity

Let users watch PRs they care about. Broadcast when someone reviews, comments, or updates the PR so watchers stay informed without checking GitHub constantly.

Subscription Management

Automatic Subscriptions

Subscribe users automatically when their actions imply interest:

They create something (they probably want to follow it)
They're assigned to something (they need to stay updated)
They comment (they're engaged with the discussion)

Manual Subscriptions

Give users subscribe/unsubscribe buttons throughout your interface so they can control what they follow.

Bulk Operations

Subscribe multiple users at once when appropriate:

All team members when a new project starts
Everyone mentioned in a document
All assignees on a task

Listing Subscriptions

Let users see all topics they're subscribed to and manage their subscriptions from a single interface.

Best Practices

Descriptive Topic Names

Use topic identifiers that clearly indicate what users are subscribing to. Include context in the name:

Good: thread-feature-requests, task-auth-bug-fix
Less clear: thread-1234, task-567

Map to Your Domain

Topics should feel natural for your application. If you have threads, PRs, tasks, or projects, those become topics. Don't force a different model.

Subscribe at the Right Time

Think about when subscription makes sense:

When users explicitly click "subscribe" or "watch"
When they take an action that implies interest (commenting, creating)
When they're assigned or mentioned

Respect Unsubscribes

Always honor unsubscribe requests immediately. Never re-subscribe someone without their explicit action.

Combine with Preferences

Broadcasts work alongside user preferences. A user might be subscribed to a topic but have preferences that control how they receive those notifications (email only, push only, etc.).

Clean Up Old Topics

When resources are deleted or archived (closed threads, completed tasks), consider whether you need to maintain the topic. Unsubscribing all users or removing inactive topics keeps things tidy.

Topics vs. Direct Notifications

Use broadcasts and topics when:

Multiple users should receive the same notification
Users want control over what they follow
The recipient list changes over time
You're broadcasting updates about shared resources

Use direct notifications (specifying user IDs) when:

Notifying someone about their personal account
Sending transactional messages (receipts, confirmations)
The notification is specific to one user
The recipient is known and fixed

Integration with Notiflows

Broadcasts integrate seamlessly with the rest of Notiflows:

Preferences Still Apply

Even if a user is subscribed to a topic, their preference settings control delivery. If they've disabled email, they won't get email notifications for broadcasts—but they might still get in-app notifications.

Templates Work the Same

Use the same notiflow templates for broadcasts as you do for direct notifications. The only difference is how you specify recipients.

Channels Work Automatically

Broadcasts go through all configured channels (in-app, email, push, etc.) just like direct notifications, respecting channel availability and user preferences.

One Workflow, Many Recipients

When you trigger a broadcast, Notiflows processes the notiflow once and then efficiently delivers to all subscribers. You get all the benefits of templates, channels, and preferences without managing recipient lists.

By using broadcasts, you give users control over what they follow while simplifying how you send notifications. No more maintaining recipient lists or querying who should receive a notification—users manage their own subscriptions, and you just broadcast.

Broadcasts

On this page