Ultra Group Do Not Disturb 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. You can determine whether the app is running in the background and implement local notification popups according to your business requirements.
Prerequisites
Before using the Do Not Disturb feature, ensure you have integrated APNs push notifications.
Do Not Disturb Configuration Dimensions
The client SDK supports multiple dimensions of Do Not Disturb settings for ultra group services:
- App Key-level Do Not Disturb settings
- Default Do Not Disturb level settings by ultra group or channel
- Do Not Disturb level settings by conversation type
- Do Not Disturb level settings by conversation
- Do Not Disturb level settings by ultra group channel
- Global Do Not Disturb
Ultra group offline message push notifications are also affected by the Ultra Group Default Push Frequency Settings in the Console. .
App-Level Do Not Disturb Settings
Configure the default Do Not Disturb level for all users of an entire application by App Key. By default, no settings are configured, which is equivalent to receiving notifications for all messages. This level of configuration is not currently available in the Console. If needed, please submit a ticket.
- Notify all messages: Users under the current App can receive push notifications for any message.
- Not set: By default, all messages trigger notifications.
- Only @ mentions notify: Users under the current App only receive push notifications for messages that mention (@) the current user or all group members.
- Only @ specific users notify: Users under the current App only receive push notifications for messages that mention (@) the current user. For example: Only Zhang San will receive notifications for messages like "@Zhang San Hello".
- Only @ all group members notify: Users under the current App only receive push notifications for messages that mention (@) all group members.
- No notifications: Users under the current App do not receive push notifications for any messages, meaning no offline messages will trigger push notifications.
- No push notifications for group messages except @ mentions: Users under the current App receive push notifications for one-to-one chat messages, messages that mention (@) specific users, and messages that mention (@) all group members.
When the RC service determines whether to send push notifications, if any of the following user-level Do Not Disturb configurations exist, the user-level configuration takes precedence:
- Do Not Disturb level settings by conversation type
- Do Not Disturb level settings by conversation
- Global Do Not Disturb
If no user-level configurations exist, the default Do Not Disturb level of the ultra group/channel to which the message belongs is used. App-level Do Not Disturb configurations have the lowest priority.
Default Do Not Disturb Level by Ultra Group/Channel
The client SDK supports configuring the categories of messages that trigger push notifications or completely disabling notifications for all members of a specified ultra group. The client SDK provides RCPushNotificationLevel, supporting the following six levels:
| Enum Value | Numeric Value | Description |
|---|---|---|
| RCPushNotificationLevelAllMessage | -1 | After disconnecting from the RC service, all users of the current ultra group can receive notifications for all messages in the specified ultra group (or channel). |
| RCPushNotificationLevelDefault | 0 | Not set. This is the initial state when no settings are configured. In this state, if both the ultra group and group channel are unset, the default Do Not Disturb level for the ultra group and channel is considered to be "notify all messages". |
| RCPushNotificationLevelMention | 1 | After disconnecting from the RC service, all users of the current ultra group only receive notifications for messages in the specified ultra group (or channel) that mention (@) the current user or all group members. |
| RCPushNotificationLevelMentionUsers | 2 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified ultra group (or channel) that mention (@) the current user. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
| RCPushNotificationLevelMentionAll | 4 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified ultra group (or channel) that mention (@) all group members. |
| RCPushNotificationLevelBlocked | 5 | The current user does not receive push notifications for any messages in the specified ultra group (or channel). |
For specific setup methods, see Setting Default Do Not Disturb for Groups/Channels.
The default Do Not Disturb logic set for a specified ultra group automatically applies to all channels under the group. If a default Do Not Disturb logic is separately configured for a channel, the channel's default settings take precedence. 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 simultaneously, the following configurations take precedence:
- Do Not Disturb level settings by conversation type
- Do Not Disturb level settings by conversation
- Do Not Disturb level settings by ultra group channel
- 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 is a user-level setting.
The client SDK provides RCPushNotificationLevel, allowing users to configure the categories of messages that trigger push notifications or completely disable notifications for conversation types (one-to-one chat, group chat, ultra group, system conversation). The following six levels are supported:
| Enum Value | Numeric Value | Description |
|---|---|---|
| RCPushNotificationLevelAllMessage | -1 | After disconnecting from the RC service, the current user can receive notifications for all messages in the specified conversation type. |
| RCPushNotificationLevelDefault | 0 | Not set. This is the initial state when no settings are configured. Note: In this state, if both the ultra group and group channel are unset, the default Do Not Disturb level for the ultra group and channel is considered to be "notify all messages". |
| RCPushNotificationLevelMention | 1 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation type that mention (@) the current user or all group members. |
| RCPushNotificationLevelMentionUsers | 2 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation type that mention (@) the current user. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
| RCPushNotificationLevelMentionAll | 4 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation type that mention (@) all group members. |
| RCPushNotificationLevelBlocked | 5 | The current user does not receive push notifications for any messages in the specified conversation type. |
For specific setup methods, see Setting 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 simultaneously, the following configurations take precedence:
- Do Not Disturb level settings by conversation
- Do Not Disturb level settings by ultra group channel
- Global Do Not Disturb
Do Not Disturb Level by Conversation
The client SDK has supported this feature since version 5.2.2. This feature is a user-level setting.
The client SDK provides RCPushNotificationLevel, allowing users to configure the categories of messages that trigger notifications or completely disable notifications for a conversation. The following six levels are supported:
| Enum Value | Numeric Value | Description |
|---|---|---|
| RCPushNotificationLevelAllMessage | -1 | After disconnecting from the RC service, the current user can receive notifications for all messages in the specified conversation type. |
| RCPushNotificationLevelDefault | 0 | Not set. This is the initial state when no settings are configured. Note: In this state, if both the ultra group and group channel are unset, the default Do Not Disturb level for the ultra group and channel is considered to be "notify all messages". |
| RCPushNotificationLevelMention | 1 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation that mention (@) the current user or all group members. |
| RCPushNotificationLevelMentionUsers | 2 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation that mention (@) the current user. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
| RCPushNotificationLevelMentionAll | 4 | After disconnecting from the RC service, the current user only receives notifications for messages in the specified conversation that mention (@) all group members. |
| RCPushNotificationLevelBlocked | 5 | The current user does not receive push notifications for any messages in the specified conversation. |
For specific setup methods, see Setting Do Not Disturb by Conversation.
Starting from 2022.09.01, the Do Not Disturb level set for a specified ultra group automatically applies to all channels under the group. 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 simultaneously, the following configurations take precedence:
- Do Not Disturb level settings by ultra group channel
- Global Do Not Disturb
Do Not Disturb Level by Ultra Group Channel
The client SDK has supported this feature since version 5.2.2. This feature is a user-level setting.
The client SDK provides RCPushNotificationLevel, allowing users to configure the categories of messages that trigger notifications or completely disable notifications for a specified ultra group channel. The following six levels are supported:
| Enum Value | Numeric Value | Description |
|---|---|---|
| RCPushNotificationLevelAllMessage | -1 | After disconnecting from the RC service, the current user can receive notifications for all messages in the specified ultra group channel. |
| RCPushNotificationLevelDefault | 0 | Not set. This is the initial state when no settings are configured. Note: In this state, if both the ultra group and group channel are unset, the default Do Not Disturb level for the ultra group and channel is considered to be "notify all messages". |
| RCPushNotificationLevelMention | 1 | After disconnecting from the RC service, the current user can receive notifications for messages in the specified ultra group channel that mention (@) the current user or all group members. |
| RCPushNotificationLevelMentionUsers | 2 | After disconnecting from the RC service, the current user can receive notifications for messages in the specified ultra group channel that mention (@) the current user. For example: Zhang San will only receive notifications for messages like "@Zhang San Hello". |
| RCPushNotificationLevelMentionAll | 4 | After disconnecting from the RC service, the current user can receive notifications for messages in the specified ultra group channel that mention (@) all group members. |
| RCPushNotificationLevelBlocked | 5 | The current user does not receive push notifications for any messages in the specified ultra group channel. |
For specific setup methods, see Setting Do Not Disturb by Channel.
When determining whether to send push notifications to users, the RC server prioritizes the configuration details of global Do Not Disturb if the user has enabled it.
Global Do Not Disturb
Starting from version 5.2.2, the client SDK provides RCPushNotificationQuietHoursLevel, allowing users to configure when to receive notifications and which message categories trigger notifications. Three levels are available:
| Enumeration | Value | Description |
|---|---|---|
| RCPushNotificationQuietHoursLevelDefault | 0 | Not set. If unset, the SDK will first check the user-level Do Not Disturb settings for the message's group and other non-user-level settings before determining whether to send push notifications. |
| RCPushNotificationQuietHoursLevelMention | 1 | When disconnected from the RC server, the current user will only receive notifications for messages that mention (@) them or all group members in specified conversations during designated time periods. |
| RCPushNotificationQuietHoursLevelBlocked | 5 | The current user will not receive push notifications for any messages during specified time periods. |
For specific setup methods, see Global Do Not Disturb.
SDK versions prior to 5.2.2 do not support configuring notification-triggering message categories and only allow enabling/disabling push notifications.
Priority of Do Not Disturb Settings
For ultra group conversations, the RC server follows this priority order when checking Do Not Disturb configurations (highest priority first):
Global Do Not Disturb (user-level) > Channel-specific Do Not Disturb in ultra groups (user-level) > Conversation-specific Do Not Disturb (user-level) > Conversation-type-specific Do Not Disturb (user-level) > Default channel Do Not Disturb in ultra groups (group-wide) > Ultra group-wide Do Not Disturb (group-wide) > App-level Do Not Disturb
API Interface List
The following table describes the Do Not Disturb configuration APIs available for ultra group conversations.
| Configuration Scope | Client API | Server API |
|---|---|---|
| Set global Do Not Disturb level for specified periods (user-level) | See Global Do Not Disturb. | See Set User Do Not Disturb Period. |
| Set channel-specific Do Not Disturb level in ultra groups (user-level) | See Channel-based Do Not Disturb. | See Set Conversation Do Not Disturb. |
| Set conversation-specific Do Not Disturb level (user-level) | See Conversation-based Do Not Disturb. | See Set Conversation Do Not Disturb. |
| Set conversation-type-specific Do Not Disturb level (user-level) | See Conversation-type-based Do Not Disturb. | See Set Conversation Type Do Not Disturb. |
| Set default Do Not Disturb for ultra groups/channels (group-wide) | See Set Default Group/Channel Do Not Disturb under "Ultra Group Management". | See Set Default Group/Channel Do Not Disturb under "Ultra Group Management". |
| Set App-level Do Not Disturb | Not available in client SDK. | Not available on server. |