Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Moderation and Security

Moderation Commands and Permissions

Build safe moderation commands for Discord and Telegram bots: permission bitfields with BigInt, role hierarchy, who may act on whom, warning escalation and audit logs.

A moderation bot holds real power: it can silence people, remove them, and delete their messages. Mistakes here are not cosmetic. A missing check lets any member ban the owner; a bug in escalation bans a user for one typo. This lesson shows how to decide who may do what, and how to structure warn, mute, kick and ban commands so each one passes the same safety gate.

The platforms differ in vocabulary, not in principle. Discord has permission bitfields and a role hierarchy. Telegram has chat member statuses and admin rights. In both, the gate asks four questions:

  1. Is the caller allowed to use this command?
  2. Is the target a valid target (not the caller, not the bot, not the owner)?
  3. Is the caller allowed to act on this particular target?
  4. Is the bot itself able to do it?

Discord permissions are a bitfield

A permission set arrives as a decimal string such as "1099511627778". It is a 64-bit number where each bit means one permission. JavaScript bitwise operators work on 32 bits and numbers lose precision above 2^53, while flags such as Timeout Members sit at bit 40, so always parse with BigInt.

Node.js Reading a permissions bitfield with BigInt

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Slash commands deliver the invoking member's computed permissions in interaction.member.permissions. Use that value rather than asking the API, because it already accounts for roles and channel overwrites in the channel where the command ran.

Role hierarchy: who can act on whom

Having BAN_MEMBERS is not enough. Discord lets you act only on members whose highest role is below yours, and the bot itself is bound by the same rule. The guild owner can never be acted on by anyone but themselves. Your bot should check hierarchy itself and give a clear message instead of letting Discord answer 403 Missing Permissions.

One gate for every moderation action

Put the four questions in one function and call it from every command.

Node.js A reusable permission gate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at the order: the cheap, caller-focused checks come first, so a regular member trying /ban learns nothing about the server. The messages are specific, so a moderator knows what to fix. Every command, /kick, /ban, /timeout, /warn, starts with this gate and only then does anything.

Telegram: statuses and admin rights

On Telegram you find out who someone is by calling getChatMember. The result has a status of creator, administrator, member, restricted, left or kicked. Administrators carry flags such as can_restrict_members and can_delete_messages. The same gate applies: only a creator or an administrator with can_restrict_members may use /mute, /ban, and the bot must itself be an administrator with that right. Telegram's restrictChatMember mutes (set permissions.can_send_messages to false, with an until_date) and banChatMember removes; unbanChatMember with only_if_banned lifts a ban. Telegram also refuses to restrict administrators and the creator, but check first to give a clean message.

JavaScript
// read-only sketch of the Telegram side
async function canUseModCommand(api, chatId, userId) {
  const m = await api("getChatMember", { chat_id: chatId, user_id: userId });
  return m.status === "creator" || (m.status === "administrator" && m.can_restrict_members === true);
}

Warnings and escalation

A moderator wants a ladder rather than an instant ban: warn, then mute, then kick, then ban. Keep the ladder as data and count active warnings in the database (SQLite storage for bots).

Node.js Escalation ladder with expiring warnings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Expiry matters. A warning from two years ago should not push someone to a ban today. Also store the moderator, the reason and the time with each action, and post it to a log channel. When members argue about a ban, an audit trail ends the argument.

Safety rules to remember

  • Never let a command run on a target that only the caller can see in their own message text; resolve IDs explicitly, not by partial name matching.
  • Put destructive actions behind a confirmation button for ban of large groups or bulk deletes. Check on the button click that the person clicking is the same moderator who ran the command.
  • Rate-limit moderation commands per moderator; a hijacked moderator account should not be able to ban the whole server in a minute.
  • Log failures as well as successes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why parse Discord permissions with BigInt?

    Permission bitfields may use high bits; Number cannot represent every 64-bit value exactly.
  2. 2. A moderator with BAN_MEMBERS tries to ban a member whose top role is higher. What should happen?

    Acting on a member requires a higher top role, except for the guild owner.
  3. 3. Which check should come first in a moderation gate?

    Caller authorization comes first, so unauthorized users learn nothing about the target.
  4. 4. Why should warnings expire?

    An escalation ladder should reflect recent behavior.

Summary

  • Parse Discord permissions as BigInt; Administrator passes every permission check.
  • Authorize in four steps: caller permission, valid target, hierarchy, bot ability.
  • On Telegram use getChatMember status and can_restrict_members.
  • Model escalation as a data ladder with expiring warnings, and keep an audit log.
  • Add confirmations and rate limits for destructive actions.

Next: Anti-spam and input validation