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:

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
ParameterDescription
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
ParameterDescription
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()
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.

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 }
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 {
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 {
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 }
    show all 33 lines
  3. Remove the event listener.

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