Skip to main content

Notifications

Notifications keep you informed about activity in your spaces. When something relevant happens—a new post, a comment on your post, a member joins—you get notified.

What is a Notification?​

A notification is a lightweight alert about space activity. Notifications are:

  • Space-scoped: Each notification belongs to a specific space
  • Activity-based: Generated from actions (posts, comments, reactions, member changes)
  • Read/unread tracking: Mark notifications as read to manage what you've seen
  • Aggregated: Similar events are grouped together to reduce noise

Notifications create awareness without overwhelming you with every minor action.

Notification Types​

Content Activity​

Post created - New post in a space you're in

Post pinned - Admin pinned a post (admins only)

Comment added - Someone commented on a post

Reaction added - Someone reacted to a post or comment

Member Activity​

Member joined - New member joined the space

Member role changed - Someone was promoted to admin or demoted to member

Member kicked - Admin removed a member (admins only)

Member banned - Admin banned someone (admins only)

Application Activity​

Application submitted - Someone applied to join (admins only, application mode spaces)

Application approved - Your application was approved (applicant only)

Application rejected - Your application was rejected (applicant only)

Application canceled - Applicant withdrew their application (admins only)

Different roles see different notifications—admins see moderation events, applicants see application status.

Aggregation​

Similar notifications are grouped together. Instead of 10 separate "new post" notifications, you get one notification showing:

  • The most recent 3 posts
  • Total count of new posts
  • Time window of activity

How it works:

Notifications of the same type in the same space within a time window get grouped. The aggregated notification shows:

  • Sample items (e.g., 3 most recent identities who reacted)
  • Total count
  • First and last activity timestamps

This keeps your notification feed manageable while preserving the information.

Read State​

Notifications start as unread. Mark them read to track what you've seen.

Marking read:

  • Individual notification: Mark one notification read
  • All notifications: Mark everything read at once

Badge counts: The API provides unread counts per space and globally, useful for showing notification badges in UIs.

Last read timestamp: Notifications track when they were last marked read, so you can show "new since you last checked" indicators.

Space Filtering​

Notifications are always tied to a space. You can:

  • Get notifications for all your spaces (global feed)
  • Filter to a specific space
  • Get per-space unread counts

This lets you build both a unified notification center and per-space activity feeds.

Notification Scope​

Each notification has a scope—the thing it's about. Scope types:

  • Post: Includes post preview (title, creator, timestamps)
  • Space: Includes space preview (name, avatar)
  • Application: Includes application details and status
  • Member ban/kick: Includes who was banned/kicked and who did it
  • Role change: Includes old role, new role, who changed it

The scope provides enough context to understand the notification without fetching additional data.

Visibility Rules​

Notifications respect privacy and role permissions:

  • Only visible to space members
  • Admin-only notifications (bans, kicks, applications) only go to admins
  • Applicant-only notifications (approval/rejection) only go to the applicant
  • Deleted content doesn't generate new notifications

Notifications are private—you only see yours.

Lifecycle​

Creation: Activity happens (post created, member joins). System creates notification for relevant users.

Delivery: Notifications appear in your feed immediately. Poll the API to get updates.

Reading: Mark notifications read as you review them.

Aggregation: New similar activity updates existing grouped notifications instead of creating duplicates.

Notifications persist—they don't disappear when read, so you can reference past activity.

Design Philosophy​

Notifications embody DFOS's approach to awareness:

Relevant: Only notify about spaces you're in and events that matter to your role.

Grouped: Aggregate similar events to prevent notification fatigue.

Contextual: Include enough preview data to understand what happened without extra fetches.

Private: Your notifications are yours—no shared or public notification feeds.

Opt-in attention: Pull-based (you poll) rather than push (no interruptions). You check when you want updates.

This creates awareness that respects your attention rather than competing for it.