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

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

Channel-member preferences are checked first (if they exist for the user on the specific channel).
If no channel-member preference exists, user-level (global) preferences are used.
If no user-level preference exists, the channel configuration push_level is used (set on the channel type or as a channel config override).
If no preferences are set at any level, the default behavior is all.
Temporary disabling: If disabled_until is set and the current time is before that timestamp, 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 preferences for multiple users
await client.setPushPreferences([
  {
    user_id: "user-1",
    chat_level: "mentions",
  },
  {
    user_id: "user-2",
    chat_level: "all",
  },
  {
    user_id: "user-3",
    chat_level: "none",
  },
]);

Channel-Member Preferences

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

// Set channel-level preferences
await client.setPushPreferences([
  {
    user_id: "user-1",
    channel_cid: "messaging:general",
    chat_level: "none",
  },
  {
    user_id: "user-1",
    channel_cid: "messaging:announcements",
    chat_level: "all",
  },
  {
    user_id: "user-2",
    channel_cid: "messaging:general",
    chat_level: "mentions",
  },
]);

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.updateChannelType("messaging", {
  push_level: "all_mentions",
});

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

# Set push_level on a channel type
client.update_channel_type("messaging", push_level="all_mentions")

# Set push_level as a channel config override on a specific channel
channel = client.channel("messaging", "announcements")
channel.update({"config_overrides": {"push_level": "all"}})

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.channel("messaging", "announcements");
await channel.update({
  config_overrides: {
    chat_preferences: {
      default_preference: "none",
      channel_mentions: "all",
      direct_mentions: "all",
    },
  },
});

# Set granular chat_preferences as a channel config override
channel = client.channel("messaging", "announcements")
channel.update({
    "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.setPushPreferences([
  {
    // 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",
  },
]);

// Client-side - can only update current user's preferences
let currentUserController = chatClient.currentUserController()
currentUserController.setPushPreference(level: .mentions)

// Set preferences for a specific channel
let channelController = chatClient.channelController(for: ChannelId(type: .messaging, id: "general"))
channelController.setPushPreference(level: .all)

// Client-side - can only update current user's preferences
client.setUserPushPreference(PushPreferenceLevel.mentions).enqueue()

// Set preferences for a specific channel
client.setChannelPushPreference("messaging:general", PushPreferenceLevel.all).enqueue()

Server-Side Usage

Server-side requests can update preferences for any user:

// Server-side - can update preferences for any user
await serverClient.setPushPreferences([
  {
    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.setPushPreferences([
  {
    user_id: "user-id",
    chat_level: "none",
  },
]);

// Later, re-enable all push notifications
await client.setPushPreferences([
  {
    user_id: "user-id",
    chat_level: "all",
  },
]);

// Disable all push notifications
currentUserController.setPushPreference(level: .none)

// Later, re-enable all push notifications
currentUserController.setPushPreference(level: .all)

// Disable all push notifications
client.setUserPushPreference(PushPreferenceLevel.none).enqueue()

// Later, re-enable all push notifications
client.setUserPushPreference(PushPreferenceLevel.all).enqueue()

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.setPushPreferences([
  {
    user_id: "user-id",
    channel_cid: "messaging:general",
    chat_level: "mentions", // Default: mentions only
  },
  {
    user_id: "user-id",
    channel_cid: "messaging:urgent-alerts",
    chat_level: "all", // Always notify for urgent alerts
  },
  {
    user_id: "user-id",
    channel_cid: "messaging:social-chat",
    chat_level: "none", // Never notify for social chat
  },
]);

// Set different preferences for different channels
// For general channel: mentions only
generalChannelController.setPushPreference(level: .mentions)

// For urgent alerts channel: always notify
urgentAlertsChannelController.setPushPreference(level: .all)

// For social chat channel: never notify
socialChatChannelController.setPushPreference(level: .none)

// Set different preferences for different channels
// For general channel: mentions only
client.setChannelPushPreference("messaging:general", PushPreferenceLevel.mentions).enqueue()

// For urgent alerts channel: always notify
client.setChannelPushPreference("messaging:urgent-alerts", PushPreferenceLevel.all).enqueue()

// For social chat channel: never notify
client.setChannelPushPreference("messaging:social-chat", PushPreferenceLevel.none).enqueue()

3: Temporarily Disabling Push Notifications

You can temporarily disable push notifications until a specific time using the disabled_until parameter. This is useful for implementing "Do Not Disturb" periods or scheduled quiet hours.

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

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

// 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.setPushPreferences([
  {
    user_id: "user-1",
    channel_cid: "messaging:general",
    chat_level: "all",
    disabled_until: tomorrow.toISOString(),
  },
]);

// Disable push notifications for 2 hours for the current user
let twoHoursFromNow = Date().addingTimeInterval(2 * 60 * 60)
currentUserController.snoozePushNotifications(until: twoHoursFromNow)

// Disable push notifications for a specific channel until tomorrow
if let tomorrow = Calendar.current.date(byAdding: .day, value: 1, to: Date()) {
    channelController.snoozePushNotifications(until: tomorrow)
}

// Disable push notifications for 2 hours for the current user
val twoHoursFromNow = Date().apply { time += 2.hours.inWholeMilliseconds }
client.snoozeUserPushNotifications(until = twoHoursFromNow).enqueue()

// Disable push notifications for a specific channel until tomorrow
val tomorrow = Date().apply { time += 1.days.inWholeMilliseconds }
client.snoozeChannelPushNotifications("messaging:general", until = tomorrow).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.

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:

If any applying category is set to all, the push is sent.
If any applying category is set to none (and none are all), the push is suppressed.
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.setPushPreferences([
  {
    user_id: "user-1",
    chat_preferences: {
      default_preference: "none",
      direct_mentions: "all",
      thread_replies: "all",
    },
  },
]);

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

# User-level: only receive pushes for direct mentions and thread replies
client.set_push_preferences([
    {
        "user_id": "user-1",
        "chat_preferences": {
            "default_preference": "none",
            "direct_mentions": "all",
            "thread_replies": "all",
        },
    },
])

# Channel-member level: mute @channel and @here in a noisy channel
client.set_push_preferences([
    {
        "user_id": "user-1",
        "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.setPushPreferences([
  {
    user_id: "user-1",
    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.setPushPreferences([
  {
    user_id: "user-1",
    call_level: "all",
    disabled_until: oneHourFromNow.toISOString(),
  },
]);

Push Providers & Multi Bundle

Legacy Push System