> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord Bot

> Self-host the GAIA Discord bot: create a Discord application, configure OAuth, and run it against your GAIA API.

# Discord Bot Development

Run your own instance of the GAIA Discord bot.

<Note>
  Looking to use GAIA on Discord as a user? See [Using GAIA on Discord](/guides/discord-bot).
</Note>

## Prerequisites

* Node.js 18+ and pnpm
* A [Discord Developer Account](https://discord.com/developers/applications)
* GAIA API running (see [Self-Hosting Guide](/self-hosting/overview))

## Step 1: Create a Discord Application

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
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`:

```bash theme={null}
DISCORD_OAUTH_CLIENT_ID=your_client_id
DISCORD_OAUTH_CLIENT_SECRET=your_client_secret
```

<Note>
  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.
</Note>

## Step 4: Configure Environment Variables

Create a `.env` file in `apps/bots/discord/`:

```bash theme={null}
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:

```bash theme={null}
nx run bot-discord:deploy-commands
```

This only needs to be run once (or whenever commands change).

## Step 6: Start the Bot

```bash theme={null}
# Development (hot reload)
nx dev bot-discord

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

## Troubleshooting

| Problem                          | Solution                                                           |
| -------------------------------- | ------------------------------------------------------------------ |
| Bot doesn't respond to commands  | Run `nx run bot-discord:deploy-commands`, check bot permissions    |
| Authentication link doesn't work | Verify `GAIA_BOT_API_KEY` matches API config                       |
| Bot offline                      | Check that the process is running and `DISCORD_BOT_TOKEN` is valid |