Documentation / Basics / How Discord bots work
- Joins with invite
The bot is added to the server via an invite link that specifies permissions.
- Listens to events
Discord sends what is happening on the server to the bot as an instant event.
- Works on request
When a bot wants to do something, it sends a request to Discord: delete message, assign role, write embed.
A Discord bot is a special account used by a program instead of a human. It is created as an application in the Discord Developer Portal, added to the server via an invite link, and managed by a program running continuously on its own server. Aegis is such a program written with the discord.js v14 library.
A bot is an application
The bot has a name, an avatar, and a secret token. The program connects to Discord using this token; since anyone who knows the token can manage the bot, it is stored only on the bot's server. The APP tag appears next to bot accounts on Discord.
Invites and permissions
Discord's invite screen is used to add a bot to your server. The link carries who the bot is and what permissions it wants. When you select the server and confirm, the bot joins the server with those permissions.
https://discord.com/oauth2/authorize?client_id=1527276218007687168&permissions=8&integration_type=0&scope=bot+applications.commands| Parameter | Type | Description | Example |
|---|---|---|---|
| client_id * | ID | Which bot to add. | 1527276218007687168 |
| permissions * | number | Sum of requested permissions. 8 is Administrator permission. | 8 |
| scope * | list | bot: joins the server as a member. applications.commands: registers slash commands. | bot+applications.commands |
| integration_type | number | 0, indicates that the bot has been added to a server. | 0 |
Events: bot's ear
As long as the bot is running, it maintains an open connection to the Discord Gateway. When something happens on the server, Discord forwards it to the bot as an event. The bot only receives the event groups (intents) it requests; for sensitive groups like member lists and message content, Discord requires additional approval.
- MESSAGE_CREATE
- New message. AutoMod catches profanity and invite links here.
- GUILD_MEMBER_ADD
- New member. Welcome, autorole, trust score, and Anti-Raid counter work.
- CHANNEL_DELETE
- Channel deleted. Anti-Nuke counts deletions.
- GUILD_ROLE_UPDATE
- Role changed. Role log is written, permission changes are tracked.
- INTERACTION_CREATE
- Someone wrote a slash command or pressed a button.
- Aegis listens to server, message, message content, member, reaction, status, moderation, invite, voice, and webhook event groups.
Requests: bot's hand
When a bot wants to do something, it sends a request to Discord's API: delete message, give role to member, open channel, send embed. Discord checks every request against the bot's permissions and role hierarchy; it rejects unauthorized requests. It also temporarily slows down bots that send requests too quickly.
Slash commands
When you type / in chat, Discord lists the commands registered by bots in the server. When you send the command, Discord passes it to the bot as an interaction. The bot must respond within 3 seconds or enter a "thinking" state; long-running commands like /setup first enter the thinking state and write the response when finished.
{
"type": "APPLICATION_COMMAND",
"data": { "name": "setup" },
"guild_id": "…",
"member": { "user": { "username": "you" } }
}How Aegis combines these
The chain of events when an administrator's account is compromised is as follows:
- 1. Event
- CHANNEL_DELETE events occur in rapid succession.
- 2. Counting
- Aegis counts the deletions by the same person in 10 seconds and compares it against the threshold (default 3).
- 3. Requests
- When the threshold is exceeded, that person's roles are revoked and server permissions are frozen.
- 4. Registration
- An embed explaining what happened is written to the guvenlik-log channel, and a DM is sent to the owner.