Permissions and moderation
Request only what you need and understand the installation ceiling.
Examples use the bot client from Your first bot.
Three checks apply
Changing requested permissions does not silently upgrade existing installations. Ask a server manager to authorize the new grants. Additional server roles cannot expand the installation ceiling.
- The application requests a capability.
- A server manager approves it through the install link, optionally restricting channels.
- The bot’s effective channel permissions and role hierarchy must allow the action.
Available capabilities
| Capability | What it allows |
|---|---|
| VIEW_CHANNEL | View allowed channels |
| SEND_MESSAGES | Send and reply |
| EMBED_LINKS | Embed links |
| ATTACH_FILES | Upload files |
| ADD_REACTIONS | Add reactions where supported |
| MANAGE_MESSAGES | Delete other members’ messages |
| MANAGE_CHANNELS | Create categories and text channels, and manage authorized text channels |
| KICK_MEMBERS | Kick lower members |
| BAN_MEMBERS | Ban lower members |
| MODERATE_MEMBERS | Time out lower members |
| MANAGE_ROLES | Manage eligible lower roles |
| MESSAGE_CONTENT | Read channel content beyond commands and mentions |
| SEND_DIRECT_MESSAGES | Start eligible DMs, subject to recipient privacy |
| CONNECT | Join visible server voice channels |
| SPEAK | Play audio in server voice channels |
Moderate within the hierarchy
Bots cannot act on the server owner or equal/higher members, manage managed roles or grant permissions beyond their installation ceiling. A timeout keeps the member in the server. Duration is one to 40,320 minutes; zero clears it. Unban does not require the target to remain a server member.
For moderation commands, register the member’s required permission as well as requesting the bot’s own capability. The server still authorizes every action.
await bot.moderate(serverId, userId, 'timeout', { durationMinutes: 10 });
await bot.setRole(serverId, userId, roleId, true);
await bot.clearTimeout(serverId, userId);
await bot.unban(serverId, bannedUserId);Look up a member and server roles
roles lists role metadata in hierarchy order. member uses the user ID and includes joinedAt, roleIds and the same role metadata. These reads require current View Channel consent and server membership. They expose server identity, rather than private profile fields. Expired managed Booster assignments are excluded.
Server staff can assign eligible custom roles to bots. Only the server owner can assign a custom Administrator role. Bot API actions still require their approved capabilities and respect selected channels and the managed integration role’s hierarchy.
Role metadata describes the server. It never expands the bot’s installation permissions.
const roles = await bot.roles(serverId);
const member = await bot.member(serverId, userId);
console.log(member.username, member.roleIds);
console.log('Server roles:', roles.items.length);