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 permenant ban.

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

The SDK can also create a new role by simply assigning a new role to a user using EkoClient.setRoles(). However, this role will be meaningless until you attach appropriate permissions to it via the SDK admin panel.

The moderation functionality in the SDK are 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 get an instance of EkoChannelModeration from EkoChannelRepository.moderate() method or from EkoChannel.moderate() method:

EkoChannelModeration moderation;
// Access from EkoChannelRepository
moderation = channelRepository.moderate(CHANNEL_ID);
// Access from EkoChannel
moderation = channel.moderate();

Mute Users

When a user is muted, all messages sent by that user will be rejected by the SDK. 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 by until unset by passing in -1.

Duration timeout = Duration.standardMinutes(10);
Collection<String> userIds = Arrays.asList("user1");
moderation.muteUsers(timeout, userIds)

The above logic will mute user1 in the selected channel for 10 minutes.

If you want to permanently mute an user, pass in Duration.millis(-1) as the timeout. The user will stay muted until you explicitly unmute that user.

To unmute an user, call EkoChannelModeration.unmuteUsers():

Collection<String> userIds = Arrays.asList("user1");

Note: This feature does not work with Broadcast and Conversation channel. Calling muteUsers() or unMuteUsers() on these channels will result in an 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.

Collection<String> userIds = Arrays.asList("user1");

There is a seperate unban call to unban an user:

Collection<String> userIds = Arrays.asList("user1");

Note: This feature does not work with Broadcast and Conversation channel. Calling banUsers() or unBanUsers() on these channels will result in an 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 message 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 perferred 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 message history and see that past message.

Duration rateLimitPeriod = Duration.standardMinutes(10);
int rateLimit = 5;
Duration rateLimitWindow = Duration.standardSeconds(60);
moderation.rateLimit(rateLimitPeriod, rateLimit, rateLimitWindow)

The above method enables a rate limit of 5 messages every 60 seconds. Once a user sends more than 5 messages in 60 seconds, his 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 EkoChannelModeration.removeRateLimit():


Note: This feature does not work with Broadcast and Conversation channel. Calling reateLimit() or removeRateLimit() on these channels will result in an error.

Flag Messages and Users

While having moderators surveying your chats is great, this doesn't scale well. A way to overcome this is to let your users do the work for your moderators: by letting users flag other users or specific messages, the work of moderators goes from scanning each message in each channel to investigate each user flag (to both users and messages) and react only when deemed necessary.

Flag Messages

In order to flag a message, create an instance of EkoMessageFlagger by calling; Beware that each EkoMessageFlagger is tied to only one specific message.

EkoMessage message;
EkoMessageFlagger flagger =;
// flag a message
.doOnComplete(() -> {
// Message is already flagged. you may update the UI accordingly here
// un-flag a message
// check whether we already have flagged this message
boolean isFlaggedByMe = message.isFlaggedByMe();
// get the number of people who already have flagged this message
int totalFlagCount = message.getFlagCount();

Flag Users

In order to flag a user, create an instance of EkoUserFlagger by calling; Beware that each EkoUserFlagger is tied to only one specific user.

EkoUser user;
EkoUserFlagger flagger =;
// flag a user
.doOnComplete(() -> {
// User is already flagged. you may update the UI accordingly here
// un-flag a user
// check whether we already have flagged this user
boolean isFlaggedByMe = user.isFlaggedByMe();
// get the number of people who already have flagged this user
int totalFlagCount = user.getFlagCount();