E-Helper

An AI-powered Discord bot for university club e-boards. Ask questions, get answers from your knowledge base.

Features

• /ask [question] - Ask anything about e-board operations
• /resources - List available resources and links
• /contacts - Show key contacts
• /reload - Reload knowledge base (admin)

Quick Start

1. Create Discord Application

1. Go to Discord Developer Portal
2. Click "New Application" → Name it "E-Helper"
3. Go to Bot tab → Click "Add Bot"
4. Copy the Bot Token (you'll need this)
5. Go to General Information → Copy Application ID and Public Key

2. Get OpenAI API Key

1. Go to OpenAI Platform
2. Create a new API key
3. Copy it (you'll need this)

3. Set Up Environment

# Clone and enter directory
cd eBoard_Discord_Bot

# Copy environment template
cp .env.example .env

# Edit .env with your keys
nano .env  # or use your preferred editor

Fill in your .env:

DISCORD_APPLICATION_ID=your_app_id
DISCORD_PUBLIC_KEY=your_public_key
DISCORD_BOT_TOKEN=your_bot_token
OPENAI_API_KEY=your_openai_key

4. Customize Knowledge Files

Edit the files in knowledge/ with your club's information:

• contacts.txt - Officers, advisor, university contacts
• resources.txt - Links to drives, templates, tools
• procedures.txt - How-to guides for common tasks
• faq.txt - Frequently asked questions

5. Deploy to Google Cloud Run

# Install Google Cloud CLI if needed
# https://cloud.google.com/sdk/docs/install

# Login and set project
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# Enable required services
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com

# Deploy
gcloud run deploy e-helper \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "DISCORD_APPLICATION_ID=$DISCORD_APPLICATION_ID" \
  --set-env-vars "DISCORD_PUBLIC_KEY=$DISCORD_PUBLIC_KEY" \
  --set-env-vars "DISCORD_BOT_TOKEN=$DISCORD_BOT_TOKEN" \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"

Copy the deployed URL (e.g., https://e-helper-xxxxx-uc.a.run.app)

6. Configure Discord Interactions Endpoint

1. Go back to Discord Developer Portal
2. Select your application
3. Go to General Information
4. Set Interactions Endpoint URL to: https://YOUR-CLOUD-RUN-URL/interactions
5. Discord will verify the endpoint (should succeed)

7. Register Slash Commands

# Install dependencies locally
pip install -r requirements.txt

# Register commands
python register_commands.py

8. Add Bot to Your Server

1. Go to OAuth2 → URL Generator
2. Select scopes: bot, applications.commands
3. Select permissions: Send Messages, Use Slash Commands
4. Copy the URL and open it in your browser
5. Select your server and authorize

Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run locally
python -m uvicorn app.main:app --reload --port 8080

For local testing with Discord, you'll need a tunnel like ngrok:

ngrok http 8080

Then use the ngrok URL as your Interactions Endpoint.

Project Structure

eBoard_Discord_Bot/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI app, Discord handling
│   ├── bot.py           # OpenAI integration
│   └── knowledge.py     # Knowledge file loader
├── knowledge/
│   ├── contacts.txt     # Club contacts
│   ├── resources.txt    # Links and templates
│   ├── procedures.txt   # How-to guides
│   └── faq.txt          # Common questions
├── Dockerfile
├── requirements.txt
├── register_commands.py
├── .env.example
└── README.md

Updating Knowledge

Simply edit the .txt files in knowledge/ and redeploy:

gcloud run deploy e-helper --source .

Or use /reload command in Discord (triggers hot reload without redeployment).

Cost

• Google Cloud Run: Free tier (2M requests/month)
• OpenAI API: ~$1-5/month with gpt-4o-mini

Total: ~$1-5/month for typical club usage

Troubleshooting

"Invalid request signature" error

• Double-check your DISCORD_PUBLIC_KEY is correct
• Make sure the interactions URL ends with /interactions

Bot doesn't respond

• Check Cloud Run logs: gcloud run logs read --service e-helper
• Verify slash commands are registered: python register_commands.py list

Cold start delay

• First request after idle may take 2-3 seconds
• This is normal for scale-to-zero; the bot defers the response and replies within seconds

License

MIT