--- title: Subscriptions description: Understanding subscriptions --- ## Subscriptions Subscriptions enable users to opt into receiving notifications about specific topics. In Notiflows, users subscribe to topics, and when you trigger a notiflow for a topic, all users subscribed to that topic receive the notification. ### What are Subscriptions? A subscription is a relationship between a user and a topic. When a user subscribes to a topic, they indicate they want to receive notifications related to that topic. When you trigger a notiflow for a topic, Notiflows automatically delivers notifications to all users who have subscribed to that topic. This publish-subscribe pattern allows you to: - Send notifications to many users without managing individual recipient lists - Let users control which topics they want to follow - Efficiently broadcast messages to interested audiences - Scale notification delivery to large numbers of subscribers ### Topics In Notiflows, subscriptions are always to topics. A topic represents a category, subject, or area of interest that users can subscribe to. Topics are identified by unique topic identifiers that you define. Examples of topics might include: - `project-updates` - Updates about a specific project - `team-announcements` - Announcements for a team - `product-releases` - New product or feature releases - `security-alerts` - Important security notifications - `weekly-digest` - Weekly summary notifications ### How Subscriptions Work **1. Users Subscribe to Topics** Users can subscribe to topics through your application interface or API. When a user subscribes to a topic, Notiflows records that relationship. **2. Trigger Notiflows for Topics** When an event occurs that should notify subscribers, you trigger a notiflow for that topic. You don't need to specify individual recipients - Notiflows automatically identifies all subscribers. **3. Automatic Fan-Out** Notiflows automatically delivers the notification to all users subscribed to the topic. This happens efficiently, even for topics with thousands of subscribers. **4. Users Can Unsubscribe** Users can unsubscribe from topics at any time. Once unsubscribed, they won't receive future notifications for that topic, but they can resubscribe later if they choose. ### Managing Subscriptions **Subscribing Users** You can subscribe users to topics individually or in batches. When subscribing multiple users, you can subscribe up to 100 users at a time for efficiency. **Unsubscribing Users** Users can be unsubscribed from topics through your application or directly by the user. Unsubscribing immediately stops future notifications for that topic. **Listing Subscriptions** You can retrieve: - All topics a user is subscribed to - All users subscribed to a specific topic - Subscription details including when the subscription was created **Subscription Properties** You can attach custom properties to subscriptions. These properties store additional information about the subscription relationship, such as: - When the user subscribed - Subscription source (where they subscribed from) - User preferences specific to that topic - Any other metadata relevant to the subscription ### Use Cases **Broadcast Notifications** Send announcements, updates, or news to all users interested in a topic without managing recipient lists manually. **Topic-Based Alerts** Allow users to subscribe to alerts about specific entities (projects, teams, products) and notify all subscribers when relevant events occur. **Opt-In Communication** Give users control over which types of notifications they receive by letting them choose topics to subscribe to. **Scalable Messaging** Efficiently send notifications to large audiences. Whether a topic has 10 subscribers or 10,000, the process is the same. **User-Controlled Preferences** Combine subscriptions with user preferences to give users granular control over their notification experience. ### Subscription Best Practices **Clear Topic Naming** Use descriptive, consistent topic identifiers that clearly indicate what notifications users will receive. This helps users understand what they're subscribing to. **Topic Organization** Organize topics logically. Consider using hierarchical naming (e.g., `project:123:updates`) or categories to group related topics. **Subscription Management UI** Provide a clear interface where users can see their subscriptions, subscribe to new topics, and unsubscribe from topics they no longer want to follow. **Respect Unsubscribes** Always honor unsubscribe requests immediately. Don't send notifications to users who have unsubscribed from a topic. **Subscription Confirmation** Consider confirming subscriptions (especially for important topics) to ensure users intended to subscribe and to verify contact information. **Regular Cleanup** Periodically review subscriptions and remove inactive or invalid subscriptions to keep your subscriber lists current. ### Subscriptions vs. Direct Notifications Subscriptions are ideal when: - Multiple users need the same notification - Users should control what they receive - You want to broadcast to audiences - Recipient lists change frequently Direct notifications (specifying recipients in the trigger) are better when: - Notifying specific individuals about personal events - Sending transactional messages - The recipient list is small and known in advance - User choice isn't relevant ### Integration with Other Concepts **Subscriptions and Preferences** Subscriptions work alongside user preferences. A user might be subscribed to a topic but have preferences that control how they receive those notifications (which channels, frequency, etc.). **Subscriptions and Notiflows** When you trigger a notiflow for a topic, it automatically uses the subscription list to determine recipients. The notiflow processes once, but creates notifications for all subscribers. **Subscriptions and Users** Only registered users can subscribe to topics. Ensure users are properly identified in Notiflows before they can subscribe. By leveraging subscriptions, you create a flexible, scalable notification system that puts users in control while simplifying the process of broadcasting messages to interested audiences.