# Discord Bot Setup Guide

> Complete guide to creating a Discord bot and connecting it to Aetheel.

---

## Table of Contents

1. [Overview](#overview)
2. [Create a Discord Application](#step-1-create-a-discord-application)
3. [Create the Bot](#step-2-create-the-bot)
4. [Enable Privileged Intents](#step-3-enable-privileged-intents)
5. [Invite the Bot to Your Server](#step-4-invite-the-bot-to-your-server)
6. [Configure Aetheel](#step-5-configure-aetheel)
7. [Run and Test](#step-6-run-and-test)
8. [Troubleshooting](#troubleshooting)
9. [Architecture Reference](#architecture-reference)

---

## Overview

Aetheel connects to Discord using the **Gateway API** via `discord.py`, which means:
- ✅ **No public URL needed** — works behind firewalls and NAT
- ✅ **No webhook setup** — Discord pushes events via WebSocket
- ✅ **Real-time** — instant message delivery
- ✅ **DMs + @mentions** — responds in both

### What You'll Need

| Item | Description |
|------|-------------|
| **Discord Account** | With access to a server where you have Manage Server permissions |
| **Bot Token** | From the Discord Developer Portal |
| **Python 3.14+** | Runtime for the Aetheel service |

---

## Step 1: Create a Discord Application

1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications)
2. Click **"New Application"**
3. Enter a name: `Aetheel` (or any name you prefer)
4. Accept the Terms of Service
5. Click **"Create"**

You'll be taken to your application's **General Information** page.

---

## Step 2: Create the Bot

1. Navigate to **Bot** in the left sidebar
2. The bot user is created automatically with your application
3. Click **"Reset Token"** to generate a new bot token
4. **⚠️ Copy the token now!** You won't be able to see it again.
   - Save it somewhere safe — this is your `DISCORD_BOT_TOKEN`

### Optional: Bot Settings

On the same Bot page, you can configure:

| Setting | Recommended | Why |
|---------|-------------|-----|
| **Public Bot** | OFF | Only you can invite it to servers |
| **Requires OAuth2 Code Grant** | OFF | Simpler invite flow |

---

## Step 3: Enable Privileged Intents

Still on the **Bot** page, scroll down to **Privileged Gateway Intents**.

Enable the following:

| Intent | Required | Purpose |
|--------|----------|---------|
| **Message Content Intent** | ✅ Yes | Read the text content of messages |
| **Server Members Intent** | Optional | Resolve member display names |
| **Presence Intent** | No | Not needed |

> **Important:** The Message Content Intent is required. Without it, the bot will receive empty message content for guild messages.

Click **"Save Changes"**.

---

## Step 4: Invite the Bot to Your Server

1. Navigate to **OAuth2** → **URL Generator** in the left sidebar
2. Under **Scopes**, check: `bot`
3. Under **Bot Permissions**, check:

| Permission | Purpose |
|------------|---------|
| **Send Messages** | Reply to users |
| **Read Message History** | Context for conversations |
| **View Channels** | See channels the bot is in |

4. Copy the **Generated URL** at the bottom
5. Open the URL in your browser
6. Select the server you want to add the bot to
7. Click **"Authorize"**

The bot should now appear in your server's member list (offline until you start Aetheel).

---

## Step 5: Configure Aetheel

### Option A: Using `.env` file (recommended)

Edit your `.env` file and add:

```env
DISCORD_BOT_TOKEN=your-discord-bot-token-here
```

### Option B: Export environment variable

```bash
export DISCORD_BOT_TOKEN="your-discord-bot-token-here"
```

---

## Step 6: Run and Test

### Install dependencies

```bash
uv sync
# or: pip install -r requirements.txt
```

This will install `discord.py` along with the other dependencies.

### Run the bot

```bash
# Discord only
uv run python main.py --discord

# Discord + Slack together
uv run python main.py --discord

# Discord with Claude Code runtime
uv run python main.py --discord --claude

# Test mode (echo handler, no AI)
uv run python main.py --discord --test

# Debug logging
uv run python main.py --discord --log DEBUG
```

### Verify it's working

1. Check the console — you should see:
   ```
   Aetheel Discord Adapter
   Bot:     @Aetheel (123456789)
   Guilds:  My Server
   ```
2. In Discord, go to a channel where the bot is present
3. Type `@Aetheel help` — you should see the help response
4. Type `@Aetheel status` — you should see the bot's status
5. Send a DM to the bot — it should respond directly

### How the bot responds

| Context | Trigger | Session Isolation |
|---------|---------|-------------------|
| **Guild channel** | @mention only | Per-channel |
| **DM** | Any message | Per-DM channel |

---

## Troubleshooting

### ❌ "Discord bot token is required"

**Problem:** `DISCORD_BOT_TOKEN` is not set or empty.

**Fix:**
1. Check your `.env` file contains the token
2. Make sure there are no extra spaces or quotes
3. Verify the token is from the Bot page, not the application client secret

### ❌ Bot comes online but doesn't respond to messages

**Problem:** Message Content Intent is not enabled.

**Fix:**
1. Go to [Developer Portal](https://discord.com/developers/applications) → your app → **Bot**
2. Scroll to **Privileged Gateway Intents**
3. Enable **Message Content Intent**
4. Save and restart Aetheel

### ❌ Bot doesn't respond in guild channels

**Problem:** You're not @mentioning the bot.

**Fix:**
- In guild channels, the bot only responds to @mentions: `@Aetheel hello`
- In DMs, the bot responds to any message — no @mention needed

### ❌ "Improper token has been passed"

**Problem:** The token is malformed or from the wrong place.

**Fix:**
1. Go to **Bot** page in the Developer Portal
2. Click **"Reset Token"** to generate a fresh one
3. Copy the full token (it's a long string)
4. Make sure you're using the Bot token, not the Client ID or Client Secret

### ❌ "discord.errors.PrivilegedIntentsRequired"

**Problem:** You're requesting intents that aren't enabled in the portal.

**Fix:**
1. Go to **Bot** → **Privileged Gateway Intents**
2. Enable **Message Content Intent**
3. Save changes and restart

### ❌ Bot is offline in the member list

**Problem:** Aetheel isn't running, or the token is wrong.

**Fix:**
1. Start Aetheel with `--discord` flag
2. Check the console for connection errors
3. Verify the token in `.env` matches the one in the Developer Portal

### ❌ "Missing Permissions" when sending messages

**Problem:** The bot doesn't have Send Messages permission in that channel.

**Fix:**
1. Check the channel's permission overrides for the bot role
2. Re-invite the bot with the correct permissions (see Step 4)
3. Or manually grant the bot's role Send Messages in Server Settings → Roles

---

## Architecture Reference

### How It Works

```
┌──────────────────────┐
│   Your Discord       │
│   Server             │
│                      │
│  #general            │
│  #random             │
│  DMs                 │
└──────┬───────────────┘
       │ WebSocket (Gateway API)
       │
┌──────▼───────────────┐
│  Aetheel Discord     │
│  Adapter             │
│                      │
│  • Token resolution  │
│  • @mention filter   │
│  • DM handling       │
│  • Message chunking  │
│    (2000 char limit) │
│  • Async dispatch    │
│    via to_thread()   │
└──────┬───────────────┘
       │ Callback
       │
┌──────▼───────────────┐
│  Message Handler     │
│                      │
│  • Echo (test)       │
│  • AI (OpenCode /    │
│    Claude Code)      │
│  • Memory + Skills   │
│  • Action tags       │
└──────────────────────┘
```

### Key Files

| File | Purpose |
|------|---------|
| `adapters/discord_adapter.py` | Core Discord adapter (Gateway, send/receive) |
| `adapters/base.py` | Abstract base class all adapters implement |
| `main.py` | Entry point — `--discord` flag enables this adapter |
| `.env` | Your Discord token (not committed to git) |

### Comparison with Other Adapters

| Feature | Slack | Telegram | Discord |
|---------|-------|----------|---------|
| **Library** | `slack_bolt` | `python-telegram-bot` | `discord.py` |
| **Connection** | Socket Mode (WebSocket) | Long polling | Gateway (WebSocket) |
| **Auth** | Bot Token + App Token | Single Bot Token | Single Bot Token |
| **Trigger (channels)** | @mention | @mention | @mention |
| **Trigger (DMs)** | Any message | Any message | Any message |
| **Text Limit** | 4000 chars | 4096 chars | 2000 chars |
| **Threading** | Native threads | Reply-to-message | N/A (per-channel) |
| **Session Isolation** | Per-thread | Per-chat | Per-channel |