React
iOS
Android
Flutter
Angular
JavaScript
Unity
Unreal
Node
Python
Ruby
PHP
Java
.NET
Go
REST// Set user-level preferences for multiple users await client.upsertPushPreferences({ preferences: [ { user_id: "user-1", chat_level: "mentions", }, { user_id: "user-2", chat_level: "all", }, { user_id: "user-3", chat_level: "none", }, ], });Push Preferences
Push preferences allow users to control how they receive push notifications. You can set preferences at both the user level (global preferences) and channel level (per-channel preferences), giving users fine-grained control over their notification experience.
How Push Preferences Work
Users must be channel members to receive push notifications regardless of their preferences.
Chat push preferences operate on two levels
- User-level preferences: These act as global preferences that apply to all channels for a user.
- Channel-level preferences: These override the global preferences for specific channels.
Chat push preferences support three levels of notifications
- all: Receive all push notifications (default).
- mentions: Receive push notifications only when mentioned.
- none: Do not receive push notifications.
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-level preferences are checked first (if they exist for the specific channel).
- If no channel-level preference exists, user-level (global) preferences are used.
- If no preferences are set at all, the default behavior is “all”.
- Temporary disabling: If
disabled_untilis 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:
Channel-Level Preferences
Set preferences for specific channels, which override user-level preferences:
// Set channel-level preferences await client.upsertPushPreferences({ preferences: [ { 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", }, ], });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.upsertPushPreferences({ 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", }, ], });// 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: "messaging: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.upsertPushPreferences({ 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.upsertPushPreferences({ preferences: [ { user_id: "user-id", chat_level: "none", }, ], }); // Later, re-enable all push notifications await client.upsertPushPreferences({ preferences: [ { 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.upsertPushPreferences({ preferences: [ { 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.upsertPushPreferences({ preferences: [ { 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.upsertPushPreferences({ preferences: [ { 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 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()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.upsertPushPreferences({ preferences: [ { user_id: "user-1", call_level: "all", disabled_until: oneHourFromNow.toISOString(), }, ], });On this page: