Do Not Disturb Feature Overview
The "Do Not Disturb" feature is used to control whether users can receive push notifications for offline messages when their client devices are offline.
- Client is offline: When there are new offline messages in a conversation, users will receive the messages via the push channel by default, and a notification will pop up. After enabling Do Not Disturb, the RC server will not trigger push notifications for related messages.
- Client is running in the background: When there are new messages in a conversation, users will receive the messages directly. If using IMLib, you need to determine whether the app is running in the background and implement the local notification pop-up based on your business requirements.
If you do not wish to receive push notifications, you can set the enablePush parameter to false in the SDK initialization configuration to request the RC server to disable the push service (for the current device). You can also configure the device not to receive push notifications when disconnecting (for the current device).
Dimensions of Do Not Disturb Settings
The client SDK supports Do Not Disturb settings for one-to-one chat, group chat, and system conversations across multiple dimensions:
- App-level Do Not Disturb settings
- Do Not Disturb level by conversation type
- Do Not Disturb level by conversation
- Global Do Not Disturb
App-Level Do Not Disturb Settings
Set the default Do Not Disturb level for all users of the entire app based on the App Key. By default, it is not set, which is equivalent to receiving notifications for all messages. This level of configuration is not yet available in the Console. If needed, please submit a ticket.
- Notify all messages: Users under the current app can receive push notifications for any messages.
- Not set: By default, all messages are notified.
- Notify only @ messages: Under the current app, only messages that mention (@) the specified user or all group members will trigger push notifications for offline users.
- Notify only @ specific users: Under the current app, users will only receive push notifications for messages that mention (@) the current user. For example, only Zhang San will receive and only receive notifications for messages like "@Zhang San Hello".
- Notify only @ all group members: Under the current app, users will only receive push notifications for messages that mention (@) all group members.
- Do not notify any messages: Under the current app, users will not receive push notifications for any messages, meaning no offline messages will trigger push notifications.
- Do not send push notifications for group chat messages except @ messages: Under the current app, users will receive push notifications for one-to-one chat messages, messages that mention (@) specific users, and messages that mention (@) all group members.
When the RC server determines whether to send push notifications, the app-level Do Not Disturb configuration has the lowest priority. If any of the following user-level Do Not Disturb configurations exist, the user-level configuration will 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
The client SDK has supported this feature since version 5.2.2.1. This feature belongs to user-level settings.
The client SDK provides PushNotificationLevel, allowing users to configure the categories of messages that trigger push notifications for conversation types (one-to-one chat, group chat, ultra group, system conversation) or to completely turn off notifications. The following six levels are provided:
| Enumeration Value | Value | Description |
|---|---|---|
| PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | After disconnecting from the RC server, the current user can receive notifications for all messages in the specified type of conversation. |
| PUSH_NOTIFICATION_LEVEL_DEFAULT | 0 | Not set. This is the initial state when not set. |
| PUSH_NOTIFICATION_LEVEL_MENTION | 1 | After disconnecting from the RC server, the current user will only receive notifications for messages that mention (@) the current user and all group members in the specified type of conversation. |
| PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | After disconnecting from the RC server, the current user will only receive notifications for messages that mention (@) the current user in the specified type of 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 server, the current user will only receive notifications for messages that mention (@) all group members in the specified type of conversation. |
| PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | The current user will not receive push notifications for any messages in the specified type of conversation. |
For specific setup methods, see Do Not Disturb by Conversation Type.
When the RC server determines whether to send push notifications to a user, if any of the following user-level Do Not Disturb configurations exist, the following configurations will take precedence:
- Do Not Disturb level by conversation
- Global Do Not Disturb
Do Not Disturb Level by Conversation
The client SDK has supported this feature since version 5.2.2. This feature belongs to user-level settings.
The client SDK provides PushNotificationLevel, allowing users to configure the categories of messages that trigger notifications for a conversation or to completely turn off notifications. The following six levels are provided:
| Enumeration Value | Value | Description |
|---|---|---|
| PUSH_NOTIFICATION_LEVEL_ALL_MESSAGE | -1 | After disconnecting from the RC server, 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 not set. |
| PUSH_NOTIFICATION_LEVEL_MENTION | 1 | After disconnecting from the RC server, the current user will only receive notifications for messages that mention (@) the current user and all group members in the specified conversation. |
| PUSH_NOTIFICATION_LEVEL_MENTION_USERS | 2 | After disconnecting from the RC server, the current user will only receive notifications for messages that mention (@) the current user 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 server, the current user will only receive notifications for messages that mention (@) all group members in the specified conversation. |
| PUSH_NOTIFICATION_LEVEL_BLOCKED | 5 | The current user will not receive push notifications for any messages in the specified conversation. |
For specific setup methods, see Do Not Disturb by Conversation.
When the RC server determines whether to send push notifications to a user, if the user has configured global Do Not Disturb, the global Do Not Disturb configuration details will take precedence.
Global Do Not Disturb
The client SDK has provided PushNotificationQuietHoursLevel since version 5.2.2, allowing users to configure when to receive notifications and the categories of messages that trigger notifications. The following three levels are provided:
| Enumeration Value | Value | Description |
|---|---|---|
| PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_DEFAULT | 0 | Not set. If not set, the SDK will query the user-level Do Not Disturb settings for the message's group and other non-user-level settings in order, and then determine whether to send push notifications. |
| PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_MENTION_MESSAGE | 1 | After disconnecting from the RC server, the current user will only receive notifications for messages that mention (@) the current user and all group members in the specified conversation during the specified period. |
| PUSH_NOTIFICATION_QUIET_HOURS_LEVEL_BLOCKED | 5 | The current user will not receive push notifications for any messages during the specified period. |
For specific setup methods, see Global Do Not Disturb.
SDK versions earlier than 5.2.2 do not support setting the categories of messages that trigger notifications, only supporting whether to receive push notifications or not.
Priority of Do Not Disturb Settings
For one-to-one chat, group chat, and system conversations, the RC server will follow the order below to search for Do Not Disturb configurations. The priority decreases from left to right, and the configuration with the highest priority will be used to determine whether to trigger push notifications:
Global Do Not Disturb settings (user-level) > Do Not Disturb settings by conversation type (user-level) > Do Not Disturb settings by conversation (user-level) > App-level Do Not Disturb settings
API Interface List
The table below describes the API interfaces applicable to Do Not Disturb configurations for one-to-one chat, group chat, and system conversations.
| Do Not Disturb Configuration Dimension | Client API | Server API |
|---|---|---|
| Set the global Do Not Disturb level for the app within a specified period. | See Global Do Not Disturb. | See Set User Do Not Disturb Period |
| Set the Do Not Disturb level by conversation type | See Do Not Disturb by Conversation Type. | See Set Do Not Disturb by Conversation Type. |
| Set the Do Not Disturb level by conversation | See Do Not Disturb by Conversation. | See Set Do Not Disturb by Conversation. |
| Set the app-level Do Not Disturb level | The client SDK does not provide an API. | The server does not provide this API. |