How Discord bots work

A bot is a program that listens to events sent by Discord and performs tasks by sending requests to Discord. This is also how Aegis understands how a raid is happening.

Documentation / Basics / How Discord bots work

  1. Joins with invite

    The bot is added to the server via an invite link that specifies permissions.

  2. Listens to events

    Discord sends what is happening on the server to the bot as an instant event.

  3. 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.

Aegis invite linkurl
https://discord.com/oauth2/authorize?client_id=1527276218007687168&permissions=8&integration_type=0&scope=bot+applications.commands
ParameterTypeDescriptionExample
client_id *IDWhich bot to add.1527276218007687168
permissions *numberSum of requested permissions. 8 is Administrator permission.8
scope *listbot: joins the server as a member. applications.commands: registers slash commands.bot+applications.commands
integration_typenumber0, 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.

Interaction sent to the bot (simplified)json
{
  "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.
Aegis can only do all of this with the permissions granted to it and to the extent allowed by the role hierarchy. Therefore, Administrator permission and a high-ranking role are recommended during setup.