# 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](#granular-chat-preferences) (`chat_preferences`) for independent control over each mention type.

## How Push Preferences Work

<admonition type="warning">

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

</admonition>

### 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](#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.

## Setting Push Preferences

### User-Level Preferences

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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
]);
```

</codetabs-item>

</codetabs>

### Channel-Member Preferences

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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
]);
```

</codetabs-item>

</codetabs>

### 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.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
});
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# 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"}})
```

</codetabs-item>

</codetabs>

<admonition type="info">

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

</admonition>

You can also set [granular chat preferences](#granular-chat-preferences) on channel config overrides instead of `push_level`. The two are mutually exclusive — setting one clears the other.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
    },
  },
});
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# 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",
        },
    },
})
```

</codetabs-item>

</codetabs>

## Client-Side vs Server-Side Usage

### Client-Side Usage

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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
]);
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
// 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)
```

</codetabs-item>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// 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()
```

</codetabs-item>

</codetabs>

### Server-Side Usage

Server-side requests can update preferences for any user:

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
]);
```

</codetabs-item>

</codetabs>

## Practical Examples

### 1: Creating a "Do Not Disturb" Mode

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
  },
]);
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

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

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

</codetabs-item>

<codetabs-item value="kotlin" label="Kotlin">

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

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

</codetabs-item>

</codetabs>

### 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.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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
  },
]);
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
// 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)
```

</codetabs-item>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// 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()
```

</codetabs-item>

</codetabs>

### 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.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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(),
  },
]);
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
// 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)
}
```

</codetabs-item>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// 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()
```

</codetabs-item>

</codetabs>

## 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.

<admonition 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.

</admonition>

### 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`.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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",
    },
  },
]);
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# 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",
        },
    },
])
```

</codetabs-item>

</codetabs>

### 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:

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// Switch from granular preferences back to a simple level
await client.setPushPreferences([
  {
    user_id: "user-1",
    chat_level: "all_mentions",
  },
]);
```

</codetabs-item>

</codetabs>

## 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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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(),
  },
]);
```

</codetabs-item>

</codetabs>


---

This page was last updated at 2026-04-10T16:29:40.040Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/php/push_preferences/](https://getstream.io/chat/docs/php/push_preferences/).