Skip to content

Setting Up the Discord Bot (Operator Guide)

This guide walks you through creating a Discord application, getting the bot token, and adding the bot to your server.

1. Create a Discord Application

  1. Go to discord.com/developers/applications and log in with your Discord account.
  2. Click New Application and give it a name (e.g. "MyExternalCortex").
  3. Go to the Bot tab in the left sidebar.
  4. Click Add Bot (or Reset Token if one already exists).
  5. Copy the Token — this is your DISCORD_TOKEN. Store it securely; you won't see it again without resetting.

2. Configure Bot Permissions

Under the Bot tab, scroll to Privileged Gateway Intents and enable:

  • Message Content Intent — required to read the text of messages the bot receives.
  • Server Members Intent — required if you want the bot to look up display names.

Save changes.

3. Generate an Invite URL

Go to OAuth2 → URL Generator and select:

  • Scopes: bot, applications.commands
  • Bot Permissions:
  • Send Messages
  • Read Message History
  • Use Slash Commands
  • Embed Links
  • Add Reactions (optional, for future features)

Copy the generated URL and open it in a browser. Select the server you want to add the bot to and click Authorize.

4. Configure Environment Variables

Add to your .env:

DISCORD_TOKEN=your_token_here
DISCORD_GUILD_ID=   # optional — leave blank to enable commands globally (may take up to 1 hour to propagate)
                    # set to your server ID to enable commands instantly (guild-scoped)

To find your Guild ID: enable Developer Mode in Discord (User Settings → Advanced), then right-click your server name and select Copy Server ID.

5. Verify

Start the bot (python main.py or docker compose up). In Discord:

  • The bot should appear online in the server member list.
  • Type /help — you should see the command list appear.
  • Send a direct message to the bot — it should respond with the onboarding prompt.

Troubleshooting

Symptom Likely cause
Bot appears offline Token is wrong or not set in .env
Slash commands not appearing Try setting DISCORD_GUILD_ID for instant propagation; global commands can take up to 1 hour
"Missing Access" error in logs Bot is missing one of the required permissions listed above
Message Content Intent warning Enable the intent in the Developer Portal under Bot → Privileged Intents