Push preferences

Users control which notifications they receive with push preferences, set through the same setPushPreferences/updatePushNotificationPreferences endpoint across products. Preferences use a per-product level field: chat_level and call_level for Chat and Video, feeds_level for Activity Feeds. All of them support temporarily disabling push until a timestamp with disabled_until.

Chat and Video Push Preferences

Push preferences allow users to control how they receive push notifications. You can set preferences at the user level (global preferences), the channel-member level (per-channel preferences), and the channel configuration level (on channel types or channel config overrides). At the user and channel-member level, preferences use chat_level; at the channel configuration level, the equivalent field is push_level. Both accept the same values. Alternatively, you can use granular per-category toggles (chat_preferences) for independent control over each mention type.

How Push Preferences Work

Warning:

Users must be channel members to receive push notifications regardless of their preferences.

Chat push preferences operate on three levels

  • Channel-member preferences: Per-channel preferences set by (or for) a specific user. These take the highest priority.
  • User-level preferences: Global preferences that apply to all channels for a user, used when no channel-member preference exists.
  • Channel configuration push_level: Set on the channel type or as a channel config override. Acts as the default for all members of that channel when no user-level or channel-member preference exists.

Chat push preferences support four levels of notifications

  • all: Receive push notifications for every message (default).
  • all_mentions: Receive push notifications when mentioned by any mention type — direct user mentions, @here, @channel, role mentions, and group mentions.
  • direct_mentions: Receive push notifications only for direct user mentions (mentioned_users). Indirect mentions like @here, @channel, role mentions, and group mentions do not trigger a push.
  • none: Do not receive push notifications.

The legacy value mentions is treated as direct_mentions for backward compatibility.

For more fine-grained control, you can use granular chat preferences instead of these levels, allowing you to toggle each mention type independently.

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

  1. Channel-member preferences are checked first (if they exist for the user on the specific channel).
  2. If no channel-member preference exists, user-level (global) preferences are used.
  3. If no user-level preference exists, the channel configuration push_level is used (set on the channel type or as a channel config override).
  4. If no preferences are set at any level, the default behavior is all.
  5. Temporary disabling: If disabled_until is set and the current time is before that timestamp, notifications are disabled regardless of other preferences.
  6. Quiet hours: If the user has a quiet hours schedule and one of its windows is active, notifications are disabled regardless of other preferences.

Setting Push Preferences

User-Level Preferences

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

// Set user-level push preferences for the current user
await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_level: "mentions",
    },
  ],
});

Channel-Member Preferences

Set preferences for a specific user on specific channels. These take the highest priority:

// Set per-channel preferences for the current user
await client.updatePushNotificationPreferences({
  preferences: [
    {
      channel_cid: "messaging:general",
      chat_level: "none",
    },
    {
      channel_cid: "messaging:announcements",
      chat_level: "all",
    },
  ],
});

Channel Configuration Push Level

You can set a default push_level on a channel type or as a channel config override. This applies to all members of matching channels who have not set their own push preferences.

// Set push_level on a channel type
await client.chat.updateChannelType({
  name: "messaging",
  push_level: "all_mentions",
});

// Set push_level as a channel config override on a specific channel
const channel = client.chat.channel("messaging", "announcements");
await channel.updateChannelPartial({
  set: { config_overrides: { push_level: "all" } },
});
Info:

Channel config overrides take precedence over the channel type default. Both accept the same values: all, all_mentions, direct_mentions, and none.

You can also set granular chat preferences on channel config overrides instead of push_level. The two are mutually exclusive — setting one clears the other.

// Set granular chat_preferences as a channel config override
const channel = client.chat.channel("messaging", "announcements");
await channel.updateChannelPartial({
  set: {
    config_overrides: {
      chat_preferences: {
        default_preference: "none",
        channel_mentions: "all",
        direct_mentions: "all",
      },
    },
  },
});

Client-Side vs Server-Side Usage

Client-Side Usage

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

// Client-side - can only update current user's preferences
await client.updatePushNotificationPreferences({
  preferences: [
    {
      // user_id is optional and will be automatically set to current user
      chat_level: "mentions",
    },
    {
      // Set preferences for a specific channel
      channel_cid: "messaging:general",
      chat_level: "all",
    },
  ],
});

Server-Side Usage

Server-side requests can update preferences for any user:

// Server-side - can update preferences for any user
await client.updatePushNotificationPreferences({
  preferences: [
    {
      user_id: "user-1",
      chat_level: "mentions",
    },
    {
      user_id: "user-2",
      chat_level: "all",
    },
  ],
});

Practical Examples

1: Creating a "Do Not Disturb" Mode

// Disable all push notifications
await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_level: "none",
    },
  ],
});

// Later, re-enable all push notifications
await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_level: "all",
    },
  ],
});

2: Channel-Specific Notification Settings

You can set different preferences for each individual channel, allowing users to customize their notification experience on a per-channel basis.

// Set different preferences for different channels
await client.updatePushNotificationPreferences({
  preferences: [
    {
      channel_cid: "messaging:general",
      chat_level: "mentions", // Default: mentions only
    },
    {
      channel_cid: "messaging:urgent-alerts",
      chat_level: "all", // Always notify for urgent alerts
    },
    {
      channel_cid: "messaging:social-chat",
      chat_level: "none", // Never notify for social chat
    },
  ],
});

3: Temporarily Disabling Push Notifications

You can temporarily disable push notifications until a specific time using the disabled_until parameter. This is useful for one-off "Do Not Disturb" periods. For a recurring schedule, use quiet hours.

// Disable push notifications for 2 hours for the current user
const twoHoursFromNow = new Date(Date.now() + 2 * 60 * 60 * 1000);

await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_level: "all",
      disabled_until: twoHoursFromNow,
    },
  ],
});

// Disable push notifications for a specific channel until tomorrow
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(9, 0, 0, 0); // 9 AM tomorrow

await client.updatePushNotificationPreferences({
  preferences: [
    {
      channel_cid: "messaging:general",
      chat_level: "all",
      disabled_until: tomorrow,
    },
  ],
});

Quiet Hours

Quiet hours is a recurring "Do Not Disturb" schedule, for example "no push from 22:00 to 07:00 on weeknights". It works like a disabled_until that repeats. While one of its windows is active, the user's push notifications are dropped, not delayed:

  • Chat message pushes, in every channel, including channels with their own preferences.
  • Video call pushes, including ringing calls, even with call_level: all. Say so in your settings UI.
  • Feeds pushes.

Reminder pushes are still delivered. Messages, unread counts and WebSocket events are not affected.

The server checks the schedule when it sends each push, so the client never has to schedule or re-send anything. A push sent right at the edge of a window can land on either side of it.

The schedule

A schedule has a timezone and 1 to 7 quiet_hours rules. Push is quiet while any rule is active.

  • timezone is an IANA time zone name, such as Europe/Amsterdam or America/New_York. Offsets like +02:00 are rejected. Daylight saving time is followed automatically.
  • Each rule has a start and an end in HH:MM local time, with two digits (9:00 is rejected). start goes from 00:00 to 23:59, and end from 00:00 to 24:00. end is exclusive, must differ from start, and wraps past midnight when it is earlier than start. 00:00 to 24:00 is a whole day.
  • days lists the days a window opens on: mon, tue, wed, thu, fri, sat and sun. Leave it out for every day. ["fri"] with 22:00 to 07:00 is quiet from Friday 22:00 until Saturday 07:00.

Setting quiet hours

Schedules are user-level only. Set one with the user-level push preference, without channel_cid:

{
  "preferences": [
    {
      "schedule": {
        "timezone": "Europe/Amsterdam",
        "quiet_hours": [
          {
            "days": ["mon", "tue", "wed", "thu", "fri"],
            "start": "22:00",
            "end": "07:00"
          },
          { "days": ["sat", "sun"], "start": "00:00", "end": "24:00" }
        ]
      }
    }
  ]
}

To remove it, send { "remove_schedule": true } instead. The stored schedule is returned in the response and in the user's push_preferences when they connect. There is no WebSocket event for changes, so other devices see them when they reconnect.

Info:

These apply to the REST request.

  • Updates merge into the stored schedule. A new timezone replaces the stored one, and quiet_hours, when sent, replaces all stored rules. Send only a timezone to keep the rules, for example when the user travels. The first schedule must have both. To replace the whole schedule in one request, send remove_schedule together with schedule.
  • An empty quiet_hours list does not clear the rules. Use remove_schedule.
  • A schedule can't be sent with disabled_until for the same user in one request, nor with channel_cid. Both fail with a 400. To switch from a snooze to a schedule, send remove_disable together with schedule. A stored snooze and a stored schedule can coexist.

On Android, setUserPushSchedule sends the whole schedule and replaces the stored one. In Dart, setPushPreferences sends a PushPreferenceInput as is, so the rules above apply.

// Quiet on weeknights from 22:00 to 07:00, and all day at the weekend
val schedule = PushSchedule(
  timezone = TimeZone.getDefault().id,
  quietHours = listOf(
    QuietHoursRule(start = "22:00", end = "07:00", days = QuietHoursDay.weekdays),
    QuietHoursRule(start = "00:00", end = "24:00", days = QuietHoursDay.weekend),
  ),
)

client.setUserPushSchedule(schedule).enqueue { result ->
  if (result is Result.Success) {
    // null if the server did not store the schedule
    val stored: PushSchedule? = result.value.schedule
  }
}

// The current user's schedule
val current: PushSchedule? = client.getCurrentUser()?.pushPreference?.schedule

// Remove the schedule
client.removeUserPushSchedule().enqueue()

Granular Chat Preferences

For more fine-grained control, use the chat_preferences object instead of chat_level. This lets users toggle push notifications independently for each mention type.

Warning:

chat_preferences and chat_level are mutually exclusive. When chat_preferences is set, chat_level is cleared (and vice versa). Do not set both in the same request.

Chat preferences fields

Field Description Values
default_preference Fallback for categories that are not explicitly set all, none
direct_mentions Direct user mentions (mentioned_users) all, none
here_mentions @here mentions (mentioned_here) all, none
channel_mentions @channel mentions (mentioned_channel) all, none
role_mentions Role mentions (mentioned_roles) all, none
group_mentions User group mentions (mentioned_group_ids) all, none
thread_replies Replies in threads all, none

Each field is optional. When a field is unset (empty), the default_preference value is used. If default_preference is also unset, notifications are allowed.

How granular preferences are evaluated

When a message is sent, the system checks which mention categories apply to the recipient (e.g., they were directly mentioned, they have one of the mentioned roles, etc.). The preference for each applying category is checked in the below order:

  1. If any applying category is set to all, the push is sent.
  2. If any applying category is set to none (and none are all), the push is suppressed.
  3. If no applying category has an explicit preference, default_preference is used.

Setting granular preferences

Granular preferences can be set at both user-level and channel-member level, following the same priority rules as chat_level.

// User-level: only receive pushes for direct mentions and thread replies
await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_preferences: {
        default_preference: "none",
        direct_mentions: "all",
        thread_replies: "all",
      },
    },
  ],
});

// Channel-member level: mute @channel and @here in a noisy channel
await client.updatePushNotificationPreferences({
  preferences: [
    {
      channel_cid: "messaging:general",
      chat_preferences: {
        default_preference: "all",
        channel_mentions: "none",
        here_mentions: "none",
      },
    },
  ],
});

Switching between chat_level and chat_preferences

Setting chat_preferences clears any existing chat_level, and setting chat_level clears any existing chat_preferences. To switch back to chat_level after using granular preferences:

// Switch from granular preferences back to a simple level
await client.updatePushNotificationPreferences({
  preferences: [
    {
      chat_level: "all_mentions",
    },
  ],
});

Call Push Preferences

You can set preferences for call-related push notifications using the call_level field.

Call push preferences support two levels of notifications

  • all: Receive all call push notifications (default).
  • none: Do not receive call push notifications.

Setting Call Push Preferences

// Set call-level preferences with temporary disabling
const oneHourFromNow = new Date(Date.now() + 60 * 60 * 1000);

await client.updatePushNotificationPreferences({
  preferences: [
    {
      user_id: "user-1",
      call_level: "all",
      disabled_until: oneHourFromNow,
    },
  ],
});

Feeds 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

  1. Global disabled_until: If set and the current time is before that timestamp, all feed notifications are disabled.
  2. Feeds level: If set to "none", all feed notifications are disabled.
  3. Event-specific preferences: For specific event types (reactions, comments, follows), these override the global feeds level.
  4. 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.updatePushNotificationPreferences({
  preferences: [
    {
      feeds_level: "all", // "all" or "none"
    },
  ],
});

Event-Specific Feeds Preferences

Control notifications for specific types of feed events:

// Set granular event preferences
await client.updatePushNotificationPreferences({
  preferences: [
    {
      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.updatePushNotificationPreferences({
  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.updatePushNotificationPreferences({
  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.updatePushNotificationPreferences({
  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.updatePushNotificationPreferences({
  preferences: [
    {
      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
        // 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.updatePushNotificationPreferences({
  preferences: [
    {
      feeds_level: "none",
      disabled_until: tomorrow.toISOString(),
    },
  ],
});

Minimal Feeds Notifications

// Only get notified for comments and mentions
await client.updatePushNotificationPreferences({
  preferences: [
    {
      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
      },
    },
  ],
});