Activity Feeds V3 is in closed alpha — do not use it in production (just yet).

Push Preferences

Push preferences for Activity Feeds allow users to control how they receive push notifications for feed events. You can set preferences at the user level to control notifications for reactions, comments, follows, and other feed activities.

How Feeds Push Preferences Work

Feeds push preferences operate at the user level

User-level preferences: Global preferences that apply to all feed activities for a user.
Event-specific preferences: Granular control over specific types of feed events (reactions, comments, follows, mentions).

Feeds push preferences support two levels of notifications

all: Receive all push notifications for feed events (default).
none: Do not receive push notifications for feed events.

Additionally, you can temporarily disable push notifications until a specific time using the disabled_until parameter.

The system evaluates preferences in the following priority order

Global disabled_until: If set and the current time is before that timestamp, all feed notifications are disabled.
Feeds level: If set to “none”, all feed notifications are disabled.
Event-specific preferences: For specific event types (reactions, comments, follows), these override the global feeds level.
Default behavior: If no preferences are set, the default is “all”.

Setting Push Preferences

User-Level Feeds Preferences

Set global push preferences that apply to all feed activities for a user:

// Set basic feeds push level
await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all", // "all" or "none"
    },
  ],
});

Event-Specific Feeds Preferences

Control notifications for specific types of feed events:

// Set granular event preferences
await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all", // Global feeds level
      feeds_preferences: {
        reaction: "all", // Receive notifications for reactions
        comment: "all", // Receive notifications for activity comments
        comment_reaction: "all", // Receive notifications for comment reactions
        follow: "none", // Don't receive notifications for new followers
        mention: "all", // Receive notifications for mentions
      },
    },
  ],
});

Temporarily Disable Feeds Notifications

Disable all feed notifications until a specific time:

// Disable feeds notifications for 2 hours
const twoHoursFromNow = new Date();
twoHoursFromNow.setHours(twoHoursFromNow.getHours() + 2);

await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all",
      disabled_until: twoHoursFromNow.toISOString(),
    },
  ],
});

Feed Event Types

The following feed event types support granular push preferences:

Built-in Event Types

Event Type	Description	Preference Key
Reactions	When someone reacts to your activities or comments	`reaction`
Comments	When someone comments on your activities	`comment`
Comment Reactions	When someone reacts to your comments	`comment_reaction`
New Followers	When someone follows you	`follow`
Mentions	When you are mentioned in activities or comments	`mention`

Custom Activity Types

You can also configure push preferences for any custom activity types using the custom_activity_types field:

await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all",
      feeds_preferences: {
        // Built-in event preferences
        reaction: "all",
        comment: "all",
        comment_reaction: "all",
        follow: "none",
        mention: "all",
        // Custom activity type preferences
        custom_activity_types: {
          milestone: "all", // Allow milestone notifications
          achievement: "all", // Allow achievement notifications
          system_alert: "none", // Block system alert notifications
          promotion: "none", // Block promotional notifications
          custom_celebration: "all", // Allow custom celebration notifications
        },
      },
    },
  ],
});

How Custom Activity Types Work:

Map any activity.type to a preference ("all" or "none")
Custom types not specified in the map default to "all"
This gives you complete control over which custom events trigger push notifications

Client-Side vs Server-Side Usage

Client-Side Usage

When using client-side authentication, users can only update their own preferences:

// Client-side: user_id is automatically set to the current user
await client.upsertPushPreferences({
  preferences: [
    {
      // user_id not needed - automatically set to current user
      feeds_level: "all",
      feeds_preferences: {
        reaction: "none",
        comment: "all",
      },
    },
  ],
});

Server-Side Usage

With server-side authentication, you can update preferences for any user:

// Server-side: can update preferences for any user
await client.updatePushNotificationPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "none",
    },
    {
      user_id: "user-2",
      feeds_preferences: {
        reaction: "all",
        comment: "none",
        follow: "all",
      },
    },
  ],
});

Follow Push Preferences

When following users or feeds, you can set push preferences to control notifications for future activities from those feeds.

Setting Follow Push Preferences

// Follow with push preference for all activities
await timeline.follow("user:alice", {
  push_preference: "all", // Receive notifications for Alice's future activities
});

// Follow with no push notifications for activities
await timeline.follow("user:bob", {
  push_preference: "none", // Don't receive notifications for Bob's activities
});

Follow Push Preference Options

Value	Description
`all`	Receive push notifications for all activities from the followed feed
`none`	Don’t receive push notifications for activities from the followed feed (default)

Note: Follow push preferences are different from user-level push preferences:

Follow push preferences control notifications from specific feeds you follow
User-level push preferences control global notification settings for all feeds

Examples

Complete Feeds Preferences Setup

// Set comprehensive feeds preferences
await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all", // Enable feeds notifications globally
      feeds_preferences: {
        // Built-in event preferences
        reaction: "all", // Get notified of all activity reactions
        comment: "all", // Get notified of all comments
        comment_reaction: "all", // Get notified of all comment reactions
        follow: "none", // Don't notify for new followers
        mention: "all", // Get notified when mentioned
        comment_reaction: "all", // Get notified of comment reactions
        // Custom activity type preferences
        custom_activity_types: {
          milestone: "all", // Allow milestone notifications
          achievement: "all", // Allow achievement notifications
          system_maintenance: "none", // Block maintenance notifications
          promotional_offer: "none", // Block promotional notifications
        },
      },
    },
  ],
});

Do Not Disturb Mode for Feeds

// Enable "Do Not Disturb" for feeds until tomorrow
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0); // 9 AM tomorrow

await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "none",
      disabled_until: tomorrow.toISOString(),
    },
  ],
});

Minimal Feeds Notifications

// Only get notified for comments and mentions
await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      feeds_level: "all",
      feeds_preferences: {
        reaction: "none", // Skip reaction notifications
        comment: "all", // Keep comment notifications
        follow: "none", // Skip follower notifications
        mention: "all", // Keep mention notifications
      },
    },
  ],
});

Push Providers & Multi Bundle