Discord Bot Setup and Configuration

The MyNATCA Discord Bot provides secure member verification, role management, and community integration for NATCA Discord servers. This guide covers complete setup, configuration, and deployment.

Prerequisites

Required Software

Node.js 18+ with npm/yarn
Git for version control
Discord Application with bot token
Auth0 Account for member verification
Supabase Project for data storage

Required Accounts

Discord Developer Account
Auth0 Developer Account
Supabase Account
(Optional) Vercel Account for deployment

Initial Setup

1. Clone and Install

# Clone the repository
git clone <repository-url> mynatca-discord
cd mynatca-discord
 
# Install dependencies
npm install
 
# Copy environment template
cp .env.example .env

2. Discord Application Setup

Create Discord Application

Go to Discord Developer Portal (opens in a new tab)
Click "New Application" and name it "MyNATCA Bot"
Navigate to "Bot" section
Click "Add Bot" and confirm
Copy the bot token for later use

Configure Bot Settings

Bot Username: MyNATCA Bot
Bot Avatar: Upload NATCA logo
Public Bot: Disabled (for security)
Require OAuth2 Code Grant: Enabled

Bot Permissions

Required permissions for proper functionality:

Text Permissions:
✅ Send Messages
✅ Use Slash Commands
✅ Read Message History
✅ Mention Everyone

General Permissions:
✅ Manage Roles
✅ Manage Nicknames
✅ View Channels
✅ Change Nickname

OAuth2 URL Generator

Go to OAuth2 > URL Generator
Select scopes:
- bot
- applications.commands
Select permissions listed above
Copy generated URL for server invitation

3. Discord Server Configuration

Invite Bot to Server

Use OAuth2 URL from previous step
Select your NATCA Discord server
Authorize with selected permissions

Role Hierarchy Setup

Critical: Bot role must be positioned above managed roles:

Server Role Hierarchy (top to bottom):
1. Server Admin
2. MyNATCA Bot          ← Bot role here
3. NEB
4. FacRep
5. Committee Member
6. Regional Rep
7. NATCA Member         ← Managed roles below
8. @everyone

Create Required Roles

Create these roles in your Discord server:

# Base roles
NATCA Member            # All verified members
Verified               # Alternative base role name
 
# Position-based roles
FacRep                 # Facility Representatives
NEB                    # National Executive Board
Committee Member       # Committee chairs/members
Regional Rep           # Regional representatives
 
# Facility-specific roles (optional)
ZTL                    # Atlanta TRACON
A90                    # Boston TRACON
# ... add other facility codes as needed
 
# Region-specific roles (optional)
Region 1
Region 2
# ... add other regions as needed

4. Environment Configuration

Edit the .env file with your configuration:

# Discord Configuration
DISCORD_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_discord_application_id
DISCORD_GUILD_ID=your_discord_server_id

# Auth0 Configuration
AUTH0_DOMAIN=natca-dev.us.auth0.com
AUTH0_CLIENT_ID=your_auth0_client_id
AUTH0_CLIENT_SECRET=your_auth0_client_secret
AUTH0_SECRET=your_auth0_secret_key
AUTH0_BASE_URL=http://localhost:3003
AUTH0_ISSUER_BASE_URL=https://natca-dev.us.auth0.com
AUTH0_SCOPE=openid profile email

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_service_key

# MySQL Configuration (for data sync)
MYSQL_HOST=your_mysql_host
MYSQL_USER=your_mysql_username
MYSQL_PASS=your_mysql_password
MYSQL_DB=your_mysql_database

# Web Server Configuration
PORT=3003
BASE_URL=http://localhost:3003
NODE_ENV=development

5. Auth0 Setup

Create Auth0 Application

Go to Auth0 Dashboard (opens in a new tab)
Create new "Regular Web Application"
Configure application settings:

Application Type: Regular Web Application
Token Endpoint Authentication Method: Post

Callback URLs Configuration

Allowed Callback URLs:
http://localhost:3003/api/auth/callback
https://your-domain.com/api/auth/callback

Allowed Logout URLs:
http://localhost:3003/api/auth/logout
https://your-domain.com/api/auth/logout

Allowed Web Origins:
http://localhost:3003
https://your-domain.com

Management API Setup

Go to APIs > Auth0 Management API
Create Machine to Machine Application
Authorize your application
Grant required scopes:
- read:users
- update:users
- create:users
- update:user_metadata
- update:user_app_metadata

Custom Claims Configuration

Add Auth0 Action for login flow:

// Auth0 Actions > Flows > Login > Post Login
exports.onExecutePostLogin = async (event, api) => {
  const memberNumber = event.user.user_metadata?.member_number;
  const facilityCode = event.user.user_metadata?.facility_code;
  const regionCode = event.user.user_metadata?.region_code;
 
  if (memberNumber) {
    api.idToken.setCustomClaim('https://mynatca.org/member_number', memberNumber);
    api.idToken.setCustomClaim('https://mynatca.org/facility_code', facilityCode);
    api.idToken.setCustomClaim('https://mynatca.org/region_code', regionCode);
    api.idToken.setCustomClaim('https://mynatca.org/discord_verified', true);
  }
};

6. Database Setup

Supabase Configuration

Create new Supabase project
Go to SQL Editor
Run the following SQL:

-- Create verification_requests table
CREATE TABLE IF NOT EXISTS verification_requests (
  id SERIAL PRIMARY KEY,
  verification_id UUID UNIQUE NOT NULL,
  discord_id TEXT NOT NULL,
  discord_username TEXT NOT NULL,
  status TEXT DEFAULT 'pending',
  auth0_user_id TEXT,
  member_number TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  expires_at TIMESTAMPTZ NOT NULL,
  completed_at TIMESTAMPTZ,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- Create indexes for performance
CREATE INDEX IF NOT EXISTS idx_verification_requests_verification_id ON verification_requests(verification_id);
CREATE INDEX IF NOT EXISTS idx_verification_requests_discord_id ON verification_requests(discord_id);
CREATE INDEX IF NOT EXISTS idx_verification_requests_status ON verification_requests(status);
 
-- Enable Row Level Security
ALTER TABLE verification_requests ENABLE ROW LEVEL SECURITY;
 
-- Create RLS policies
CREATE POLICY "Service role can manage verification requests" ON verification_requests
  FOR ALL USING (auth.role() = 'service_role');

Database Connection Test

# Test Supabase connection
node -e "
const { createClient } = require('@supabase/supabase-js');
const client = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);
client.from('verification_requests').select('count').then(console.log);
"

7. Deploy and Test

Deploy Discord Commands

# Deploy slash commands to Discord
npm run deploy

Start Development Servers

# Terminal 1: Start Discord bot
npm run dev
 
# Terminal 2: Start web interface
npm run web:dev

Verify Setup

Check bot appears online in Discord
Try /register command with test member number
Verify verification link generation
Test Auth0 login flow
Confirm role assignment

Troubleshooting

Common Issues

Bot Not Responding to Commands

Check bot permissions in Discord
Verify bot role hierarchy
Check Discord token validity
Confirm guild ID is correct

Auth0 Integration Errors

Verify callback URLs in Auth0 dashboard
Check Management API permissions
Confirm environment variables
Review Auth0 logs in dashboard

Database Connection Issues

Test Supabase connectivity
Verify service key permissions
Check RLS policies
Review database logs

Debug Mode

# Enable debug logging
NODE_ENV=development DEBUG=mynatca:* npm run dev
 
# Test specific components
npm run test:auth0
npm run test:discord
npm run test:database

This setup guide provides everything needed to deploy and maintain the MyNATCA Discord Bot in both development and production environments.

Environment Variables Deployment Guide