Skip to main content

​
Permissions

Aphonos requires specific Discord permissions to perform moderation, management, and utility functions. You can configure these permissions either through server role settings or in the Discord Developer Portal.

​
Permission configuration methods

There are two ways to grant Aphonos the permissions it needs:

Role permissions

Configure permissions through the bot’s role in your server settings

Bot permissions

Set permissions in the Discord Developer Portal before inviting

​
Required permissions

Here are the permissions Aphonos needs to function properly:
Role Permissions (In-server)Bot Permissions (Dev Portal)Required For
Kick, Approve and Reject MembersKick Members/kick command
Ban MembersBan Members/ban command
Time out membersModerate Members/timeout command
Manage MessagesManage Messages/clear, /archives commands
Send MessagesSend MessagesSending responses and embeds
Embed LinksEmbed LinksRich embed responses
Read Message HistoryRead Message HistoryMessage archiving, context
Add ReactionsAdd ReactionsReaction roles, interactive features
View ChannelsView ChannelsAccessing channels for commands
These are the core permissions. Some features may require additional permissions. For self-hosted instances, consider enabling all permissions for full functionality.

​
Setting up permissions

1

Navigate to server settings

Open your Discord server and go to Server Settings → Roles
2

Find the bot's role

Locate the role that was automatically created when you invited Aphonos (it usually has the same name as the bot)
3

Configure permissions

Enable the following permissions for the bot’s role:
  • Kick Members
  • Ban Members
  • Moderate Members (for timeouts)
  • Manage Messages
  • Send Messages
  • Embed Links
  • Read Message History
  • Add Reactions
  • View Channels
4

Save changes

Click Save Changes at the bottom of the page

​
Method 2: Bot permissions (Developer Portal)

1

Open the Developer Portal

Go to the Discord Developer Portal and select your application
2

Generate OAuth2 URL

Navigate to OAuth2 → URL Generator
3

Select scopes

Check the following scopes:
  • bot
  • applications.commands
4

Select permissions

Under Bot Permissions, select:
  • Kick Members
  • Ban Members
  • Moderate Members
  • Manage Messages
  • Send Messages
  • Embed Links
  • Read Message History
  • Add Reactions
  • View Channels
5

Use the generated URL

Copy the generated URL and use it to invite the bot to your server with the correct permissions

​
Permission details

​
Moderation permissions

Required for the /kick command. Allows Aphonos to remove members from the server without banning them.
Required for the /ban command. Allows Aphonos to permanently ban members from the server.
Required for the /timeout command. Allows Aphonos to temporarily timeout members, preventing them from sending messages or joining voice channels.

​
Management permissions

Critical for the /clear command and message archiving features. Allows Aphonos to delete messages and maintain message history.

​
Communication permissions

Essential permission that allows Aphonos to send command responses and notifications in text channels.
Necessary for the /archives command and message context. Allows Aphonos to access previous messages in channels.

​
Interactive permissions

Required for reaction role features and interactive commands. Allows Aphonos to add emoji reactions to messages.
Fundamental permission that allows Aphonos to see and access channels where it should operate.

​
Gateway Intents

In addition to permissions, Aphonos requires the following Privileged Gateway Intents to be enabled in the Discord Developer Portal: 
// These intents are configured in src/index.ts
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,              // Guild information
    GatewayIntentBits.GuildMessages,       // Message events
    GatewayIntentBits.MessageContent,      // Read message content
    GatewayIntentBits.GuildMembers,        // Member events
    GatewayIntentBits.GuildModeration,     // Moderation events
    GatewayIntentBits.GuildMessageReactions // Reaction events
  ]
});

​
Enabling Privileged Intents

1

Go to Developer Portal

Navigate to the Discord Developer Portal and select your bot
2

Open Bot settings

Click on the Bot tab in the left sidebar
3

Enable Privileged Intents

Scroll down to the Privileged Gateway Intents section and enable:
  • Server Members Intent (required for member join events and /kick, /ban, /timeout)
  • Message Content Intent (required for reading message content)
4

Save changes

Click Save Changes
If your bot is in more than 100 servers, you’ll need to verify your bot and apply for these intents through Discord.

​
Role hierarchy

For moderation commands to work properly, Aphonos’s role must be positioned higher in the role hierarchy than the users it’s moderating.
1

Open Server Settings

Go to Server Settings → Roles
2

Drag the bot's role

Drag Aphonos’s role above the roles of users you want the bot to moderate
3

Important note

The bot cannot moderate users with roles higher than or equal to its own role, including the server owner

​
Channel-specific permissions

You can restrict Aphonos to specific channels using channel permission overrides:
  1. Right-click on a channel → Edit Channel
  2. Go to Permissions → Click + next to Roles/Members
  3. Select the Aphonos role
  4. Grant or deny specific permissions for that channel
For moderation channels, ensure Aphonos has View Channels, Send Messages, and Embed Links permissions.

​
Self-hosting recommendations

If you’re self-hosting Aphonos for your own server:
For simplicity and full functionality, consider giving the bot Administrator permission. This grants all permissions and bypasses channel-specific overrides.However, only do this if you trust the bot’s code and hosting environment, as Administrator permission is very powerful.
Alternatively, enable all individual permissions listed above to maintain granular control.

​
Troubleshooting permission issues

  • Verify the bot has Kick Members or Ban Members permission
  • Check that the bot’s role is higher than the target user’s role
  • Ensure the target user is not the server owner
  • Confirm the bot has Manage Messages permission
  • Check for channel-specific permission overrides that may deny this permission
  • Make sure the bot has Embed Links permission
  • Check channel-specific overrides
  • Verify the bot has View Channels permission
  • Check channel-specific permission overrides
  • Ensure the bot’s role has access to the category if the channel is in one

​
Verifying permissions

You can verify Aphonos’s permissions by checking the startup logs:
Console output
Permissions:
================================
Server: Your Server Name (ID: 123456789)
  Text: #general (ID: 987654321) - CAN READ
  Text: #moderation (ID: 192837465) - CAN READ
================================
The bot logs its visibility and read access for all channels on startup, helping you identify any permission issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us