Skip to main content

​
Discord Bot Development

Run your own instance of the GAIA Discord bot.
Looking to use GAIA on Discord as a user? See Using GAIA on Discord.

​
Prerequisites

​
Step 1: Create a Discord Application

  1. Go to the Discord Developer Portal
  2. Click New Application and give it a name
  3. Navigate to the Bot section and click Add Bot
  4. Under Privileged Gateway Intents, enable:
    • Message Content Intent
    • Server Members Intent (optional)
  5. Copy the Bot Token

​
Step 2: Configure OAuth2 Scopes

  1. Go to OAuth2 → URL Generator
  2. Select scopes: bot and applications.commands
  3. Select bot permissions: Send Messages, Use Slash Commands, Read Message History
  4. Copy the generated URL and use it to invite the bot to your server

​
Step 3: Set Up OAuth for Account Linking

This enables users to link their Discord account from the GAIA web app via OAuth instead of the /auth bot command.
  1. In your Discord application, go to OAuth2
  2. Under Redirects, add: 
    http://localhost:8000/api/v1/platform-auth/discord/callback
https://your-api-domain.com/api/v1/platform-auth/discord/callback
  3. Copy your Client ID (shown at the top of the OAuth2 page)
  4. Click Reset Secret to generate a Client Secret and copy it
Add to apps/api/.env: 
DISCORD_OAUTH_CLIENT_ID=your_client_id
DISCORD_OAUTH_CLIENT_SECRET=your_client_secret
The Client ID here is the same as your DISCORD_CLIENT_ID used by the bot, it’s the application ID, not a separate credential.

​
Step 4: Configure Environment Variables

Create a .env file in apps/bots/discord/: 
DISCORD_BOT_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_discord_client_id
GAIA_API_URL=http://localhost:8000
GAIA_BOT_API_KEY=your_secure_bot_api_key
GAIA_BOT_API_KEY must match the value configured in your GAIA API.

​
Step 5: Deploy Slash Commands

Register the bot’s slash commands with Discord: 
nx run bot-discord:deploy-commands
This only needs to be run once (or whenever commands change).

​
Step 6: Start the Bot

# Development (hot reload)
nx dev bot-discord

# Production
nx build bot-discord && nx start bot-discord

​
Troubleshooting

ProblemSolution
Bot doesn’t respond to commandsRun nx run bot-discord:deploy-commands, check bot permissions
Authentication link doesn’t workVerify GAIA_BOT_API_KEY matches API config
Bot offlineCheck that the process is running and DISCORD_BOT_TOKEN is valid