bot.player.moderation

The bot.player.moderation API handles all in-room moderation actions. Kick, mute, ban, unmute, and unban users.

Important

The bot must be a moderator or made by room owner to use these methods. If the bot lacks permission, requests will fail with ok: false.

Methods

kick(userId)

Removes a user from the room. They can rejoin immediately.

const result = await bot.player.moderation.kick(userId);

if (result.ok) {
    await bot.message.send('User has been kicked.');
}

Returns: AcknowledgmentResponse

mute(userId, duration)

Prevents a user from sending chat messages for a duration.

// mute for 60 seconds
await bot.player.moderation.mute(userId, 60);

// mute for 1 hour
await bot.player.moderation.mute(userId, 3600);

Returns: AcknowledgmentResponse

unmute(userId)

Removes an active mute from a user.

await bot.player.moderation.unmute(userId);

Returns: AcknowledgmentResponse

ban(userId, duration)

Bans a user from the room for a duration.

// ban for 1 hour
await bot.player.moderation.ban(userId, 3600);

// ban for 24 hours
await bot.player.moderation.ban(userId, 86400);

Returns: AcknowledgmentResponse

unban(userId)

Removes an active ban from a user.

Note

This requires the bot to be created by the room owner.

await bot.player.moderation.unban(userId);

Returns: AcknowledgmentResponse

Complete example

const mutedUsers = new Map();

bot.on('Chat', async (user, message) => {
    const cmd = message.command();

    if (cmd === '!kick') {
        const target = message.mentions(0) || message.args(0);

        if (!target) {
            await bot.message.send('Usage: !kick @username');
            return;
        }

        const found = await bot.room.users.find(target);

        if (!found) {
            await bot.message.send(`${target} is not in the room.`);
            return;
        }

        const result = await bot.player.moderation.kick(found.user.id);

        if (!result.ok) {
            await bot.message.send(`Could not kick ${target}: ${result.error}`);
            return;
        }

        await bot.message.send(`${target} has been kicked.`);
        return;
    }

    if (cmd === '!mute') {
        const target = message.mentions(0) || message.args(0);
        const duration = Number(message.args(1)) || 60;

        if (!target) {
            await bot.message.send('Usage: !mute @username [seconds]');
            return;
        }

        const found = await bot.room.users.find(target);

        if (!found) {
            await bot.message.send(`${target} is not in the room.`);
            return;
        }

        const result = await bot.player.moderation.mute(found.user.id, duration);

        if (!result.ok) {
            await bot.message.send(`Could not mute ${target}: ${result.error}`);
            return;
        }

        await bot.message.send(`${target} has been muted for ${duration} seconds.`);
        return;
    }

    if (cmd === '!unmute') {
        const target = message.mentions(0) || message.args(0);

        if (!target) {
            await bot.message.send('Usage: !unmute @username');
            return;
        }

        const found = await bot.room.users.find(target);

        if (!found) {
            await bot.message.send(`${target} is not in the room.`);
            return;
        }

        const result = await bot.player.moderation.unmute(found.user.id);

        if (!result.ok) {
            await bot.message.send(`Could not unmute ${target}: ${result.error}`);
            return;
        }

        await bot.message.send(`${target} has been unmuted.`);
        return;
    }
});

// Log all moderation actions
bot.on('Moderation', (moderator, target, action) => {
    console.log(`${moderator.id} performed ${action.type} on ${target.id}`);
});

AcknowledgmentResponse

{
    ok: boolean;           // true if the action succeeded
    error: string | null;  // error message if failed
    hasError(): boolean;
}

Important things to know

Your bot must be a moderator or made by room owner. If the bot is not a moderator, all methods will return ok: false with an error explaining the lack of permission.

Durations are in seconds. Pass 60 for one minute, 3600 for one hour, 86400 for one day.

Unban requires the bot to be created by the room owner. This is a Highrise limitation. If your bot was not created by the room owner, unban() will fail.

The Moderation event fires for all these actions. You can listen to bot.on('Moderation') to log or respond to moderation events from any source, including other moderators.