Moderate misbehaving users

Apart from moderation mechanisms designed for chat administrators, the Chat SDK provides moderation options for regular chat users. Users whose Chat SDK instances weren't initialized with the secretKey (as it's restricted to admins) can decide to hide messages from undesirable users.

The user IDs that a given chat user wants to hide messages from (mute them) are saved to a list. This mute list is soft-limited to 200 users and, by default, is only persisted for the duration of the user session.

You can decide to save and retrieve a local mute list during client initialization, effectively persisting the mute list beyond the scope of a single session, but then the hard 32KiB server data limit applies.

Mute list user limit

A persisted mute list can hold roughly up to 200 users (32KiB of data). If the size of the list exceeds that limit, the Chat SDK throws an HTTP 413 error and the list won't be persisted. The users will still be muted for the duration of the session.

All events and messages originating from a muted user are still received by the client, but are ignored. The mute list affects the following means of message delivery:

• channel.connect()
• channel.join()
• channel.getHistory()
• chat.listenForEvents()
• chat.getEventsHistory()

Requires App Context

To mute users, you must enable App Context for your app's keyset in the Admin Portal.

Mute users as a regular chat user

As a regular chat user, you can mute a specific user on all channels.

Method signature

1Chat.MutedUsersManager.muteUser(userId: String): PNFuture<Unit>

Input

* required

Parameter	Description
userId * Type: string	User ID of the user you want to mute.

Output

This method returns a PNFuture<Unit> that succeeds when the data has been synced with the server. If syncMutedUsers is not enabled, the PNFuture<Unit> always succeeds.

Errors

If the size of the mute list exceeds 32KiB (roughly 200 users), you'll get the HTTP 413 (Request Entity Too Large) error.

Sample code

1import com.pubnub.chat.Chat
2import com.pubnub.chat.config.ChatConfiguration
3

4val chat = Chat.init(
5    ChatConfiguration(
6        publishKey = "demo",
7        subscribeKey = "demo",
8        userId = "myUniqueUserId"
9    )
10)
11

12val userToMute = "user_1905"
13

14chat.mutedUsersManager.muteUser(userToMute).await()

Unmute users as a regular chat user

You can unmute a specific user on all channels. This removes the user from the mute list, allowing the client to see all messages and events originating from the user again.

Method signature

1Chat.MutedUsersManager.unmuteUser(userId: String): PNFuture<Unit>

Input

* required

Parameter	Description
userId * Type: string	User ID of the user you want to unmute.

Output

This method returns a PNFuture<Unit> that succeeds when the data has been synced with the server. If syncMutedUsers is not enabled, the PNFuture<Unit> always succeeds.

Sample code

1import com.pubnub.chat.Chat
2import com.pubnub.chat.config.ChatConfiguration
3

4val chat = Chat.init(
5    ChatConfiguration(
6        publishKey = "demo",
7        subscribeKey = "demo",
8        userId = "myUniqueUserId"
9    )
10)
11

12val userToUnmute = "user_1905"
13

14chat.mutedUsersManager.unmuteUser(userToUnmute).await()

Check muted users

You can check which users have been muted by inspecting the items in the mute list.

Method signature

1Chat.MutedUsersManager.mutedUsers

Output

This property returns a Set<String> where each String is a user ID of a muted user.

Sample code

1import com.pubnub.chat.Chat
2import com.pubnub.chat.config.ChatConfiguration
3

4val chat = Chat.init(
5    ChatConfiguration(
6        publishKey = "demo",
7        subscribeKey = "demo",
8        userId = "myUniqueUserId"
9    )
10)
11

12val userToMute = "user_1905"
13

14// Mute the user
15chat.mutedUsersManager.muteUser(userToMute).await()
16

17// Once the user is muted, get the list of muted users
18val mutedUsers = mutedUsersManager.mutedUsers
19

20println("Muted users: $mutedUsers")

show all 20 lines

Persist the mute list

By default, the mute list is only persisted for the duration of the user session. You can save and retrieve the mute list during client initialization, effectively persisting the mute list by setting the syncMutedUsers parameter to true during client initialization.

Mute list and Access Manager

If you use Access Manager for user moderation within your chat app and syncMutedUsers is enabled, you must grant the Chat SDK user the following permissions:

• read permission to the PN_PRV.$currentUserId.mute1 channel.
• update, delete, and get permissions for the PN_PRV.$currentUserId.mute1 user.

Make sure to change $currentUserId to the user ID of the chat user that will use the mute list functionality.

Check restrictions

You can check if the chat administrator imposed any mute or ban restrictions for the following scenarios. Refer to the linked sections for more information.

• For a single user on a single channel
• For a single user on all channels
• For all users on a single channel

Sample code

Single user on a single channel

1// reference the "chat" object and invoke the "getUser()" method
2chat.getUser("support_agent_15").async { userResult ->
3    userResult.onSuccess { user ->
4        if (user != null) {
5            // get the "support" channel
6            chat.getChannel("support").async { channelResult ->
7                channelResult.onSuccess { channel ->
8                    if (channel != null) {
9                        // get the channel restrictions for the user
10                        user.getChannelRestrictions(channel).async { restrictionResult ->
11                            restrictionResult.onSuccess { restriction ->
12                                // handle the restriction object
13                            }.onFailure {
14                                // handle failure
15                            }
16                        }
17                    } else {
18                        // handle null channel
19                    }
20                }.onFailure {
21                    // handle failure to get the channel
22                }
23            }
24        } else {
25            // handle null user
26        }
27    }.onFailure {
28        // handle failure to get the user
29    }
30}

show all 30 lines

All users on a single channel

1// reference the "chat" object and invoke the "getChannel()" method
2chat.getChannel("support").async { result ->
3    result.onSuccess { channel ->
4        if (channel != null) {
5            // fetch the user restrictions for the channel
6            channel.getUsersRestrictions().async { restrictionsResult ->
7                restrictionsResult.onSuccess { getRestrictionsResponse ->
8                    // process the returned restrictions
9                    for (restriction in getRestrictionsResponse.restrictions) {
10                        if (restriction.mute || restriction.ban) {
11                            // handle the restriction object (either muted or banned)
12                            println("User ${restriction.userId} is restricted in channel ${channel.id}: mute=${restriction.mute}, ban=${restriction.ban}")
13                        }
14                    }
15                }.onFailure {
16                    // handle the failure of getting restrictions
17                    println("Failed to get user restrictions: ${it.message}")
18                }
19            }
20        } else {
21            // handle null channel
22            println("Channel is not found.")
23        }
24    }.onFailure {
25        // handle failure
26    }
27}

show all 27 lines

Single user on all channels

1// reference the "chat" object and invoke the "getUser()" method
2chat.getUser("support_agent_15").async { result ->
3    result.onSuccess { user ->
4        if (user != null) {
5            // fetch the channel restrictions for the user
6            user.getChannelsRestrictions().async { restrictionsResult ->
7                restrictionsResult.onSuccess { getRestrictionsResponse ->
8                    // process the returned restrictions
9                    for (restriction in getRestrictionsResponse.restrictions) {
10                        if (restriction.mute || restriction.ban) {
11                            // handle the restriction object (either muted or banned)
12                            println("User is restricted on channel ${restriction.channelId}: mute=${restriction.mute}, ban=${restriction.ban}")
13                        }
14                    }
15                }.onFailure {
16                    // handle the failure of getting restrictions
17                    println("Failed to get channel restrictions: ${it.message}")
18                }
19            }
20        } else {
21            // handle null user
22            println("User is not found.")
23        }
24    }.onFailure {
25        // handle failure
26    }
27}

show all 27 lines

Secure moderation

Client-side restrictions can easily be bypassed if not secured with an additional server-side logic that uses Access Manager to allow or block user's access to PubNub resources (channels and users). This server-side can also be followed by additional client-side errors that inform app users about their restrictions up front.

Client-side restrictions

Once you enable and define server-side permissions with Access Manager, you can be sure that your muting and banning restrictions are always enforced.

Additionally, you can read moderation restrictions set with the Chat SDK methods also on your app's frontend to let a given user know upfront that they are muted on a channel or banned from accessing a channel using popup messages, iconography, etc. For example, before a user tries to write a message on a channel where they are muted and tries to search for the input field that is either greyed out or unavailable, you can display a popup message informing them about the restriction.

To let the client application react in real-time to changes in user permissions and present this information to the users effectively, the app needs to listen to and act on changes in moderation events:

1. Listen for moderation events.

   Set up a listener to listen for the moderation event type ("banned," "muted," or "lifted") generated when UI restrictions are added or removed.

   1val handleModerationEvent: (event: Event<EventContent.Moderation>) -> Unit
   2// ...
   3
   
   4val userId = chat.currentUser.id // Storing the user ID for reuse
   5val unsubscribe = chat.listenForEvents<EventContent.Moderation>(
   6    channel = "PUBNUB_INTERNAL_MODERATION.$userId", // Ensure it matches the expected format
   7    customMethod = null, // Explicitly specify if no custom method is used
   8    callback = handleModerationEvent
   9)
   10
   
   11// ...
   12// Remove the moderation event listener on cleanup
   13unsubscribe.close()

2. Act on moderation events.

   Update permissions in response to moderation events and generate new tokens if necessary.

   1fun handleModerationEvent(event: Event<EventContent.Moderation>) {
   2    val restriction = event.payload.restriction
   3    val channelId = event.payload.channelId
   4    val reason = event.payload.reason
   5
   
   6    // Handle different moderation events
   7    when (restriction) {
   8        RestrictionType.BAN -> {
   9            // Revoke specific permissions for banning
   10            println("User ${chat.currentUser.id} is banned on channel ${channelId}. Reason: ${reason ?: "N/A"}");
   11
   
   12            // Revoke access rights specific to banning logic here
   13            // For example, you might remove write access
   14
   
   15        }
   16        RestrictionType.MUTE -> {
   17            // Revoke specific permissions for muting
   18            println("User ${chat.currentUser.id} is muted on channel ${channelId}. Reason: ${reason ?: "N/A"}")
   19
   
   20            // Revoke access rights specific to muting logic here
   21            // For example, you might remove read and write access
   22        }
   23        RestrictionType.LIFT -> {
   24            // Grant access rights back
   25            println("User ${chat.currentUser.id} restrictions lifted on channel $channelId");
   26
   
   27            // Granting access rights logic here
   28        }
   29    }
   30
   
   31    // Call your backend method to issue a new token after any moderation event
   32    // Use the updated token as needed
   33}

   show all 33 lines

3. Remove the event listener.

   1// remember to call close when you're done 
   2unsubscribe.close()