Moderate misbehaving users
Requires App Context
To work with stored user metadata, you must enable App Context for your app's keyset in the Admin Portal.
Unity Chat SDK provides moderation mechanisms for:
- Admins to mute misbehaving users on channels.
- Admins to ban misbehaving users from accessing channels.
For example, an admin can mute or ban the users from a given channel using Access Manager.
Mute or ban users
As an admin, you can mute a specific user on a channel or ban them from accessing that channel using SetRestriction()
and SetRestrictions()
methods.
All of them give the same output. The only difference is that you call a given method on the Chat
, User
, or the Channel
object. Depending on the object, these methods take a different set of input parameters.
When an admin mutes or bans a user on a channel, a moderation
event is created (of type muted
or banned
). You can listen to these events and, for example, remove user's membership on that channel.
Also, when an admin mutes or bans a user, an additional moderation membership is created for that user. This membership copies the ID of the channel and adds the PUBNUB_INTERNAL_MODERATION_
prefix to it, even though no new channel gets created for that purpose.
The additional membership is created only for the moderation purposes - when fetching all channel memberships for a given user with the GetMemberships()
method, you won't see the moderation membership as Unity Chat SDK filters it out automatically with App Context Filtering Language.
When you lift restrictions on the user (unmute or unban them), the moderation membership is removed and a moderation
event of type lifted
is created.
To learn if a user is muted on a given channel or banned, use the Unity Chat SDK methods to check moderation restrictions.
Requires Secret Key authentication
Mute and ban restrictions for the client devices should be set by servers initializing Unity Chat SDK with a Secret Key (available on the Admin Portal on your app's keyset).
The SecretKey
should only be used within a secure server and never exposed to client devices. If the SecretKey
is ever compromised, it can be an extreme security risk to your application. If you suspect your SecretKey
has been compromised, you can generate a new SecretKey
for the existing PubNub keyset on the Admin Portal.
Method signature
These methods take the following parameters:
-
SetRestriction()
(on theChat
object)chat.SetRestriction(
string userId,
string channelId,
Restriction restriction
) -
SetRestriction()
(on theUser
object)user.SetRestriction(
string channelId,
Restriction restriction
) -
SetRestrictions()
(on theChannel
object)channel.SetRestrictions(
string userId,
Restriction restriction
)
Input
Parameter | Type | Required for Chat | Required for User | Required for Channel | Default | Description |
---|---|---|---|---|---|---|
userId | string | Yes | No | No | n/a | Unique User ID that becomes your app's current user. It's a string of up to 92 characters that identifies a single client (end user, device, or server) that connects to PubNub. Based on User ID, PubNub calculates pricing for your apps' usage. User ID should be persisted and remain unchanged. If you don't set userId , you won't be able to connect to PubNub. In this method, userId stands for the user that you want to mute or ban. |
channelId | string | Yes | No | No | n/a | ID of the channel on/from which the user should be muted or banned. |
restriction | Restriction | No | No | No | n/a | Moderation restrictions and reasoning behind them. |
→ ban | boolean | No | No | No | n/a | Value that represents the user's moderation restrictions. Set to true to ban the user from the channel or to false to unban them. |
→ mute | boolean | No | No | No | n/a | Value that represents the user's moderation restrictions. Set to true to mute the user on the channel or to false to unmute them. |
→ reason | string | No | No | No | n/a | Reason why you want to ban or mute the user. |
Output
These methods don't return data.
Basic usage
Mute
Mute support_agent_15
on the support
channel.
-
SetRestriction()
(on theChat
object)chat.SetRestriction(
userId: "support_agent_15",
channelId: "support",
restriction: new Restriction()
{
Ban = false,
Mute = true,
Reason = string.Empty
}
); -
SetRestriction()
(on theUser
object)if (chat.TryGetUser("support_agent_15", out var user))
{
user.SetRestriction(
channelId: "support",
restriction: new Restriction()
{
Ban = false,
Mute = true,
Reason = string.Empty
}
)
} -
SetRestrictions()
(on theChannel
object)if (chat.TryGetChannel("support", out var channel))
{
channel.SetRestrictions(
userId: "support_agent_15",
restriction: new Restriction()
{
Ban = false,
Mute = true,
Reason = string.Empty
}
)
}
Ban
Ban support_agent_15
from the support
channel.
-
SetRestriction()
(on theChat
object)if (chat.TryGetUser("support_agent_15", out var user))
{
user.SetRestriction(
channelId: "support",
restriction: new Restriction()
{
Ban = false,
Mute = true,
Reason = string.Empty
}
)
} -
SetRestriction()
(on theUser
object)if (chat.TryGetUser("support_agent_15", out var user))
{
user.SetRestriction(
channelId: support,
banUser: true,
muteUser: false,
reason: null
);
} -
SetRestrictions()
(on theChannel
object)if (chat.TryGetChannel("support", out var channel))
{
channel.SetRestrictions(
userId: "support_agent_15",
restriction: new Restriction()
{
Ban = false,
Mute = true,
Reason = string.Empty
}
)
}
Check restrictions
One user on one channel
Check if there are any mute
or ban
restrictions set for a user on one channel using the GetChannelRestriction()
and GetUserRestriction()
methods.
Method signature
These methods take the following parameters:
-
GetChannelRestrictions()
user.GetChannelRestrictions(Channel channel)
-
GetUserRestrictions()
channel.GetUserRestrictions(User user)
Input
Parameter | Type | Required in GetChannelRestrictions() | Required in GetUserRestrictions() | Default | Description |
---|---|---|---|---|---|
channel | Channel | Yes | No | n/a | Channel on/from which the user can be muted or banned. |
user | User | No | Yes | n/a | User that can be muted or banned. |
Output
These methods return a Restriction
object.
public struct Restriction
{
public bool Ban;
public bool Mute;
public string Reason;
}
Basic usage
Check if the user support_agent_15
has any restrictions set on the support
channel.
-
GetChannelRestrictions()
if (!chat.TryGetChannel("support", out var channel))
{
Console.WriteLine("Couldn't find channel!");
return;
};
if (!chat.TryGetUser("support_agent_15", out var user))
{
Console.WriteLine("Couldn't find user!");
return;
};
// check user restrictions
var restriction = user.GetChannelRestrictions(channel) -
GetUserRestrictions()
if (!chat.TryGetChannel("support", out var channel))
{
Console.WriteLine("Couldn't find channel!");
return;
};
if (!chat.TryGetUser("support_agent_15", out var restrictedUser))
{
Console.WriteLine("Couldn't find user!");
return;
};
channel.GetUserRestrictions(restrictedUser)
One user on all channels
Check if there are any mute
or ban
restrictions set for a user on all channels they are a member of using the GetChannelsRestrictions()
method.
Method signature
This method takes the following parameters:
user.GetChannelsRestrictions(
string sort = "",
int limit = 0,
Page page = null
)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
sort | string | No | empty string | Key-value pair of a property to sort by, and a sort direction. Available options are id , name , and updated . Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"} . By default, the items are sorted by the last updated date. |
limit | int | No | 0 | Number of objects to return in response. |
page | Page | No | null | Object used for pagination to define which previous or next result page you want to fetch. |
Output
Type | Description |
---|---|
ChannelsRestrictionsWrapper | An object containing the filtered, sorted, and paginated list of user restrictions. |
Basic usage
List all mute
and ban
restrictions set for the user support_agent_15
.
if(!chat.TryGetUser("support_agent_15", out var user)){
return;
}
var restrictionsWrapper = user.GetChannelsRestrictions();
foreach(var restriction in restrictionsWrapper.Restrictions)
{
Console.WriteLine($"Channel: {restriction.ChannelId}, Ban: {restriction.Ban}, Mute: {restriction.Mute}");
}
All users on one channel
Check if there are any mute
or ban
restrictions set for members of a given channel using the GetUsersRestrictions()
method.
Method signature
This method takes the following parameters:
channel.GetUsersRestrictions(
string sort = "",
int limit = 0,
Page page = null
)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
sort | string | No | empty string | Key-value pair of a property to sort by, and a sort direction. Available options are id , name , and updated . Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"} . By default, the items are sorted by the last updated date. |
limit | int | No | 0 | Number of objects to return in response. |
page | Page | No | null | Object used for pagination to define which previous or next result page you want to fetch. |
Output
Type | Description |
---|---|
UsersRestrictionsWrapper | An object containing the filtered, sorted, and paginated list of restricted users. |
Basic usage
List all mute
and ban
restrictions set for the support
channel.
var restrictionsWrapper = channel.GetUsersRestrictions();
foreach(var userRestriction in restrictionsWrapper.Restrictions)
{
Console.WriteLine(
$"User: {userRestriction.UserId}, " +
$"Banned: {userRestriction.Ban}, " +
$"Muted: {userRestriction.Mute}, " +
$"Reason: {userRestriction.Reason}");
}
Secure moderation
You could try to use only the banning or muting restrictions on client devices and enforce some UI moderation, like not displaying channels for users who are banned from them, or not displaying input field for users who are muted on a given channel so that they couldn't post a message.
Still, such solely 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.
Server-side restrictions
It's recommended to use Access Manager alongside the Unity Chat SDK methods and grant or revoke permissions from users based on their muting or banning restrictions.
For example, you could have a UI moderation dashboard where admins set restrictions on users by muting or banning them from specific channels. After that, you can use one of the Unity Chat SDK methods to get moderation restrictions for users and, based on results, call the Access Manager API to either generate or revoke grant tokens for PubNub resources (channels or users).
Let's look at sample steps to configure a chat app, set up server permissions, listen to any permission changes, and invoke access grant or revoke request on the server side.
-
Enable Access Manager.
Navigate to your app's keyset in the Admin Portal and turn on the ACCESS MANAGER option.
-
Initialize Unity Chat SDK with
AuthKey
.On the frontend of your app, initialize the Unity Chat SDK with the authentication key (
AuthKey
) on your clients. Use it for all requests made to PubNub APIs to authenticate users in your application and grant them access to PubNub resources (other users' metadata and channels). -
Secure backend initialization.
On the backend, initialize the Unity SDK with the secret key (
SecretKey
) on your servers to secure your PubNub instance.Secret key
SecretKey
is a secret shared between your application's server and PubNub and it's used to administer Access Manager permissions for your client applications by signing and verifying the authenticity of messages and requests. Remember to never expose theSecretKey
to client devices. -
Get user permissions.
Retrieve detailed user restrictions and convert these details into a simplified permission format where each channel is marked with whether the user can read, write, or access it, based on such restrictions as bans or mutes using the Get user details and Check restrictions methods.
-
Generate authorization token.
Using the Unity SDK, generate and assign an access token reflecting the user's permissions.
The token contains information about which channels the user can access and how (read/write), and it's configured with a specific validity period. This token serves as a key for users to interact with the application according to their permissions.
Operation-to-permission mapping
Read the Permissions document for a complete list of available operations that users can do with PubNub resources in apps created with the Unity Chat SDK.
Set short TTLs
You can mute or ban a user for an indefinite amount of time, but you can unmute/unban them at any time. To make sure that the permissions set with Access Manager reflect the most up-to-date muting/banning restrictions on the client-side, it's recommended to set short-lived tokens (TTLs) for grant calls (valid for seconds and minutes rather than hours or days). Alternatively, if new muting/banning restrictions are set on the frontend side of your app, you can revoke Access Manager permissions on the backend using the
chat.sdk.RevokeToken()
method. -
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. -
Act on moderation events.
Update permissions in response to moderation events and generate new tokens if necessary.
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 Unity 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.
Listen to Moderation
events
As an admin of your chat app, you can use the StartListeningForModerationEvents()
method to send notifications to the affected user when you mute or ban them on a channel, or to remove user channel membership each time they are banned.
Events documentation
To read more about the events of type Moderation
, refer to the Chat events documentation.
Method signature
This method has the following parameters:
// start listening
chat.StartListeningForModerationEvents(string userId)
// triggered moderation event
public event Action<ModerationEvent> OnModerationEvent;
// needs a corresponding event handler
void EventHandler(ModerationEvent event)
Input
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
userId | string | Yes | n/a | User for which to receive all new Moderation events. |
Output
These operations don't return any data.
Basic usage
Send a Moderation
event to the muted user.
chat.StartListeningForModerationEvents("support_agent_15")
chat.OnModerationEvent += OnModerationEventHandler; // or use lambda
void OnModerationEventHandler(ModerationEvent moderationEvent)
{
Console.WriteLine($"Moderation event received, payload: {moderationEvent.Payload}");
}
// set restrictions for the user