Moderation

Moderation is an important tool for building a safe community that encourages user participation. However, it is important to note that any moderation tool should be used carefully, as excessive moderation can achieve the opposite effect of preventing user from participating in a conversation. Ideally, we encourage a tiered incident escalation policy, where a user first receive a verbal warning, then a temporary mute, to a permanent ban.

Please note that by default, users do not have access to these moderation methods. Any call to these methods will return an incorrect permissions error. To give a user moderation permissions, please first create a role in the Upstra admin panel, attach moderation permissions to that role, and assign that role to the user via the setRoles method. See Miscellaneous for more details.

Upstra can also create a new role by simply assigning a new role to a user using setRoles. However, this role will be meaningless until you attach appropriate permissions to it via Upstra's admin panel.

The moderation functionality in Upstra is enabled on a per channel basis, this gives you the ability to define different moderation parameters for each individual channel. In order to access moderation methods, you must first instantiate the ChannelModerationRepository class using the EkoClient instance you created on setup, as well as a valid channelId:

import { ChannelModerationRepository } from 'eko-sdk';
const repository = new ChannelModerationRepository('channel1');

Mute Users

When a user is muted, all messages sent by that user will be rejected by Upstra. This method is useful for preventing certain users from sending inappropriate messages, but still allowing them to participate in the conversation in a read-only manner. The timeout property allows you to make the timeout temporary, or permanent until it is unset by passing in -1.

repository.muteMembers({
userIds: ['user1'],
period: 600,
}).catch(error => {
...
});

The above logic will mute user1 in the selected channel for 10 minutes (600 seconds). An optional completion block notifies you when the action is complete.

If you want to permanently mute a user, pass in -1 as the mutePeriod. The user will stay muted until you explicitly unmute that user.

To unmute a user, call unmuteUsers():

repository.unmuteMembers({
userIds: ['user1'],
}).catch(error => {
...
});

Ban Users

Banning users is a more heavy handed moderation method. When a user is banned, all his messages are retroactively deleted, he will be removed from the channel, and he will not be allowed to join the channel again until he is explicitly unbanned.

repository.banMembers({
userIds: ['user1'],
}).catch(error => {
...
});

There is a separate unban call to unban a user:

repository.unbanMembers({
userIds: ['user1'],
}).catch(error => {
...
});

Rate Limit Channel

Rate limiting a channel controls the speed of messages that is published to all concurrent clients in the channel. This method is useful when there is a large amount of messages going through the channel, which can make the message stream hard to follow. Setting a rate limit enables the SDK to queue up messages once the amount of messages in a specified window exceeds the defined limit, allowing a slower stream of messages to be published to the user at the expense of adding more latency (because newer messages will be sent to the queue first and not delivered until all previous queued messages are delivered).

There is an internal limit of 1000 messages that can be queued by the rate limit service, if more than 1000 messages are queued up, the system may skip publishing the older messages in order to make room for newer messages. We think this is the preferred behavior for users, as users will most likely want to see newer messages in a real-time conversation instead of waiting for a significant amount of time for old messages to be published to them first.

Note that the SDK permanently stores all messages it receives in the system before the rate limit comes into effect. This means in the case of a large spike of incoming messages, even if a message did not get published to a user in real-time, that user can still scroll up to see the message history and that past message.

repository.setRateLimit({
period: 600,
rateLimit: 5,
rateLimitWindow: 60,
}).catch(error => {
...
});

The above method enables a rate limit of 5 messages every 60 seconds. Once a user sends more than 5 messages in 60 seconds, their messages will be queued on the server and not published to other channel members until 60 seconds have passed.

In order to disable the rate limit, simply call removeRateLimit():

repository.removeRateLimit().catch(error => {
...
});