Do Not Disturb Feature Overview
The Do Not Disturb feature controls whether users can receive push notifications for offline messages when their client devices are offline.
- Client offline status: When new offline messages arrive in a conversation, users receive them through the push channel by default with notifications displayed. When Do Not Disturb is enabled, the RC service will not trigger push notifications for related messages.
- Client running in background: When new messages arrive in a conversation, users receive them directly. If using IMLib, you need to determine whether the app is running in the background and implement local notification popups based on business requirements.
If push notifications are not required, you can disable the push service (for the current device) by setting the enablePush parameter to false in the SDK initialization configuration during first installation. You can also configure the device to not receive push notifications when disconnecting.
Do Not Disturb Configuration Dimensions
The IMLib SDK supports Do Not Disturb settings across multiple dimensions for one-to-one chat, group chat, and system conversation services:
- App Key-level Do Not Disturb settings
- Do Not Disturb level by conversation type
- Do Not Disturb level by conversation
- Global Do Not Disturb
App Key-Level Do Not Disturb Settings
Configure default Do Not Disturb levels for all users under an App Key. By default, no settings are applied, meaning all messages trigger notifications. This level of configuration is not currently available in the Console. Submit a ticket if needed.
- Notify all messages: Users under this App Key can receive push notifications for any message.
- Not set: Defaults to notifying all messages.
- Only notify @mentions: Offline users under this App Key receive push notifications only for messages that mention (@) them or all group members.
- Only notify @mentions of specific users: Users under this App Key receive notifications only for messages that mention (@) them. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello".
- Only notify @all mentions: Users under this App Key receive notifications only for messages that mention (@) all group members.
- Block all notifications: Users under this App Key do not receive push notifications for any messages.
- No push notifications for group messages except @mentions: Users under this App Key receive push notifications for one-to-one messages, messages that mention (@) them, and messages that mention (@) all group members.
When determining whether to send push notifications, the RC service gives the lowest priority to App Key-level Do Not Disturb settings. If any of the following user-level configurations exist, they take precedence:
- Do Not Disturb level by conversation type
- Do Not Disturb level by conversation
- Global Do Not Disturb
Do Not Disturb Level by Conversation Type
Client SDKs support this feature starting from version 5.2.2.1. This is a user-level setting.
The client SDK provides PushNotificationLevel, allowing users to configure which message categories trigger push notifications for conversation types (one-to-one chat, group chat, ultra group, system conversation) or to disable notifications entirely. Six levels are available:
Parameter Description
| Enum Value | Numeric Value | Description |
|---|---|---|
PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | After disconnecting from the RC service, the current user can receive notifications for all messages in the specified conversation type. |
PUSH_NOTIFICATION_LEVEL_DEFAULT | 0 | Not set. This is the initial state when no settings are applied. |
PUSH_NOTIFICATION_LEVEL_MENTION | 1 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) them or all group members in the specified conversation type. |
PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) them in the specified conversation type. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
PUSH_NOTIFICATION_LEVEL_MENTION_ALL | 4 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) all group members in the specified conversation type. |
PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | The current user does not receive push notifications for any messages in the specified conversation type. |
For specific configuration methods, see Do Not Disturb by Conversation Type.
When the RC service determines whether to send push notifications to a user, if any of the following user-level Do Not Disturb configurations exist, they take precedence:
- Do Not Disturb level by conversation
- Global Do Not Disturb
Do Not Disturb Level by Conversation
Client SDKs support this feature starting from version 5.2.2. This is a user-level setting.
The client SDK provides PushNotificationLevel, allowing users to configure which message categories trigger notifications for a conversation or to disable notifications entirely. Six levels are available:
| Enum Value | Numeric Value | Description |
|---|---|---|
PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | After disconnecting from the RC service, the current user can receive notifications for all messages in the specified conversation. |
PUSH_NOTIFICATION_LEVEL_DEFAULT | 0 | Not set. This is the initial state when no settings are applied. |
PUSH_NOTIFICATION_LEVEL_MENTION | 1 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) them or all group members in the specified conversation. |
PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) them in the specified conversation. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
PUSH_NOTIFICATION_LEVEL_MENTION_ALL | 4 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) all group members in the specified conversation. |
PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | The current user does not receive push notifications for any messages in the specified conversation. |
For specific configuration methods, see Do Not Disturb by Conversation.
When the RC service determines whether to send push notifications to a user, if the user has configured Global Do Not Disturb, the Global Do Not Disturb settings take precedence.
Global Do Not Disturb
Starting from version 5.2.2, the client SDK provides PushNotificationQuietHoursLevel, allowing users to configure when to receive notifications and which message categories trigger them. Three levels are available:
| Enum Value | Numeric Value | Description |
|---|---|---|
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_DEFAULT | 0 | Not set. If not set, the SDK checks user-level Do Not Disturb settings for the message's group and other non-user-level settings to determine whether to send push notifications. |
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_MENTION_MESSAGE | 1 | After disconnecting from the RC service, the current user receives notifications only for messages that mention (@) them or all group members in the specified conversation during the configured time period. |
PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_BLOCKED | 5 | The current user does not receive push notifications for any messages during the specified time period. |
For specific configuration methods, see Global Do Not Disturb.
SDK versions earlier than 5.2.2 do not support configuring which message categories trigger notifications; they only support enabling or disabling push notifications.
Do Not Disturb Setting Priorities
For one-to-one chat, group chat, and system conversations, the RC service follows the order below to check Do Not Disturb configurations. Priority decreases from left to right, and the highest-priority configuration determines whether to trigger push notifications:
Global Do Not Disturb (user-level) > Do Not Disturb by conversation type (user-level) > Do Not Disturb by conversation (user-level) > App-level Do Not Disturb
API Interface List
The table below describes API interfaces for configuring Do Not Disturb settings for one-to-one chat, group chat, and system conversations.
| Do Not Disturb Configuration Dimension | Client API | Server API |
|---|---|---|
| Configure Global Do Not Disturb level for the entire app during specified periods. | See Global Do Not Disturb. | See Set User Do Not Disturb Period |
| Configure Do Not Disturb level by conversation type | See Do Not Disturb by Conversation Type. | See Set Do Not Disturb by Conversation Type. |
| Configure Do Not Disturb level by conversation | See Do Not Disturb by Conversation. | See Set Do Not Disturb by Conversation. |
| Configure App-level Do Not Disturb level | Not provided in client SDK. | Not provided on the server. |