Skip to main content
This comprehensive guide covers everything you need to install, configure, and deploy WhatsApp Group Manager. Follow the sections relevant to your use case.

​
Prerequisites

Before installing WhatsApp Group Manager, ensure you have the following:

​
Required Software

Node.js 18+

JavaScript runtime required for Next.jsDownload Node.js

pnpm

Fast, disk-efficient package manager
npm install -g [email protected]

MongoDB

NoSQL database for data storageMongoDB Atlas (Cloud) or local installation

WAHA Server

WhatsApp HTTP API for connectivityWAHA Documentation

​
Required Services

Option 1: MongoDB Atlas (Recommended for beginners)
  1. Create a free account at MongoDB Atlas
  2. Create a new cluster (free tier available)
  3. Add your IP to the whitelist (or allow access from anywhere for development)
  4. Create a database user with read/write permissions
  5. Get your connection string (looks like mongodb+srv://user:[email protected]/dbname)
Option 2: Local MongoDB
# macOS (with Homebrew)
brew install mongodb-community
brew services start mongodb-community

# Ubuntu/Debian
sudo apt install mongodb
sudo systemctl start mongodb

# Windows
# Download installer from mongodb.com
WAHA provides the WhatsApp connectivity layer. You have several options:Option 1: Docker (Recommended)
docker run -d \
  --name waha \
  -p 3000:3000 \
  -e WHATSAPP_API_KEY=your-secret-key \
  devlikeapro/waha
Option 2: Cloud HostedUse a cloud-hosted WAHA instance from providers or deploy to your own VPS.Option 3: NPM
npm install -g @waha/waha
waha start
Make note of your WAHA URL (default: http://localhost:3000) and API key for configuration.
Required for password reset and admin notification emails:
  1. Sign up at Mailgun
  2. Verify your email domain (or use sandbox domain for testing)
  3. Get your API key from the dashboard
  4. Note your domain name (e.g., mg.yourdomain.com)
Mailgun offers 5,000 free emails per month, perfect for most use cases.

​
Local Development Setup

1

Clone Repository

Clone the WhatsApp Group Manager repository from GitHub:
git clone https://github.com/jevil25/whatsapp-group-manager.git
cd whatsapp-group-manager
2

Install Dependencies

Install all project dependencies using pnpm:
pnpm install
This command will:
  • Install all packages from package.json
  • Run the postinstall script to generate Prisma client
  • Set up the development environment
3

Configure Environment Variables

Create your environment configuration file:
cp .env.example .env
Edit .env with your actual configuration:
# Database Configuration
DATABASE_URL="mongodb+srv://username:[email protected]/whatsapp-manager"

# WhatsApp API (WAHA) Configuration
WAHA_API_URL="http://localhost:3000"
WAHA_API_KEY="your-waha-api-key"

# Better Auth Configuration
BETTER_AUTH_SECRET="generate-random-secret-here"
BETTER_AUTH_URL="http://localhost:3001"

# Mailgun Configuration for Email
MAILGUN_API_KEY="key-xxxxxxxxxxxxxxxxxxxxxxxx"
MAILGUN_DOMAIN="mg.yourdomain.com"
FROM_EMAIL="[email protected]"

# Admin Notification Configuration
ADMIN_EMAIL="[email protected]"
ADMIN_PHONE_NUMBER="+1234567890"

# Optional: Footer Configuration
NEXT_PUBLIC_SHOW_FOOTER="true"
Never commit your .env file to version control. It contains sensitive credentials.
4

Generate Secure Secrets

Generate a cryptographically secure secret for Better Auth:
# Using OpenSSL (macOS/Linux)
openssl rand -base64 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
Use the output as your BETTER_AUTH_SECRET value.
5

Set Up Database

Push the Prisma schema to your MongoDB database:
pnpm db:push
This creates all necessary collections:
  • user - User accounts and authentication
  • session - User sessions
  • account - OAuth accounts and passwords
  • WhatsAppSession - WhatsApp connection sessions
  • WhatsAppGroup - Synced WhatsApp groups
  • MessageCampaign - Message campaigns
  • Message - Individual scheduled messages
  • Verification - Email verification tokens
Run pnpm db:studio to open Prisma Studio and visually inspect your database.
6

Start Development Server

Launch the Next.js application:
pnpm dev
The application will start on http://localhost:3001
7

Start Message Scheduler

In a separate terminal, start the background scheduler:
pnpm scheduler:start
The scheduler:
  • Runs independently of the Next.js app
  • Checks for pending messages every 30 seconds
  • Automatically sends messages at scheduled times
  • Logs all activity to the console
The scheduler must run continuously for automated message delivery. In production, use PM2 or similar process manager.

​
Production Deployment

​
Frontend Deployment (Vercel)

Deploy the Next.js application to Vercel for optimal performance:
1

Push to GitHub

Ensure your code is committed and pushed to GitHub:
git add .
git commit -m "Ready for deployment"
git push origin main
2

Import to Vercel

  1. Visit Vercel
  2. Click “Add New Project”
  3. Import your GitHub repository
  4. Configure project settings:
    • Framework Preset: Next.js
    • Build Command: pnpm build (default)
    • Output Directory: .next (default)
3

Configure Environment Variables

Add these environment variables in Vercel dashboard:
DATABASE_URL=mongodb+srv://user:[email protected]/whatsapp-manager
BETTER_AUTH_SECRET=your-production-secret-key
BETTER_AUTH_URL=https://your-app.vercel.app
WAHA_API_URL=http://your-waha-server:3000
WAHA_API_KEY=your-production-waha-key
MAILGUN_API_KEY=your-mailgun-key
MAILGUN_DOMAIN=mg.yourdomain.com
[email protected]
[email protected]
ADMIN_PHONE_NUMBER=+1234567890
Use different secrets and API keys for production. Never use development credentials in production.
4

Deploy

Click “Deploy” and wait for the build to complete. Vercel will:
  • Install dependencies
  • Run Prisma generation
  • Build the Next.js application
  • Deploy to CDN
Your app will be available at https://your-app.vercel.app

​
Backend Scheduler (DigitalOcean VPS)

The message scheduler needs to run on a server 24/7. Here’s how to deploy it to a VPS:
1

Create DigitalOcean Droplet

Create a VPS to run the scheduler:
  1. Get $200 in credits (referral link)
  2. Create a new Droplet:
    • Distribution: Ubuntu 22.04 LTS
    • Plan: Basic ($6/month, 1GB RAM is sufficient)
    • Datacenter: Choose closest to your WAHA server
    • Authentication: SSH keys recommended (or password for beginners)
A basic 1GB RAM droplet can handle thousands of scheduled messages efficiently.
2

Initial Server Setup

Connect to your server and set up the environment:
# Connect via SSH
ssh root@your-server-ip

# Update system packages
apt update && apt upgrade -y

# Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
apt-get install -y nodejs

# Install pnpm globally
npm install -g [email protected]

# Install PM2 for process management
npm install -g pm2

# Install Git
apt install -y git
3

Deploy Application

Clone your repository and set up the scheduler:
# Clone repository
cd /opt
git clone https://github.com/jevil25/whatsapp-group-manager.git
cd whatsapp-group-manager

# Install dependencies
pnpm install

# Create production environment file
nano .env.production
Add your production environment variables:
DATABASE_URL="mongodb+srv://user:[email protected]/whatsapp-manager"
WAHA_API_URL="http://your-waha-server:3000"
WAHA_API_KEY="your-production-waha-key"
Save and exit (Ctrl+X, then Y, then Enter).
4

Generate Prisma Client

Generate the Prisma client for production:
pnpm prisma:generate
5

Start with PM2

Use PM2 to run the scheduler as a persistent background service:
# Start scheduler with PM2
pm2 start src/scripts/messageScheduler.ts \
  --interpreter ./node_modules/.bin/tsx \
  --name whatsapp-scheduler \
  --env production

# Save PM2 process list
pm2 save

# Configure PM2 to start on system boot
pm2 startup
The scheduler will now:
  • Run automatically on server restart
  • Restart automatically if it crashes
  • Log all activity for monitoring
6

Monitor Scheduler

Useful PM2 commands for managing the scheduler:
# Check status
pm2 status

# View real-time logs
pm2 logs whatsapp-scheduler

# View last 100 lines
pm2 logs whatsapp-scheduler --lines 100

# Restart scheduler
pm2 restart whatsapp-scheduler

# Stop scheduler
pm2 stop whatsapp-scheduler

# View detailed metrics
pm2 monit

​
Updating Production Deployment

To update your production scheduler: 
# SSH into your server
ssh root@your-server-ip

# Navigate to project directory
cd /opt/whatsapp-group-manager

# Pull latest changes
git pull origin main

# Install any new dependencies
pnpm install

# Regenerate Prisma client if schema changed
pnpm prisma:generate

# Restart scheduler
pm2 restart whatsapp-scheduler

​
Environment Variables Reference

​
DATABASE_URL
string
required
MongoDB connection stringFormat: mongodb+srv://username:[email protected]/database-nameExample: mongodb+srv://admin:[email protected]/whatsapp-prod
​
WAHA_API_URL
string
required
Base URL of your WAHA serverExample: http://localhost:3000 or https://waha.yourdomain.com
​
WAHA_API_KEY
string
required
API key for authenticating with WAHAExample: abc123xyz789
​
BETTER_AUTH_SECRET
string
required
Secret key for Better Auth session encryptionGenerate with: openssl rand -base64 32Example: xK8vN2mP9qR4sT5uV6wX7yZ8aB1cD2eF3gH4iJ5kL6==
​
BETTER_AUTH_URL
string
required
Base URL of your applicationDevelopment: http://localhost:3001Production: https://your-app.vercel.app
​
MAILGUN_API_KEY
string
required
Mailgun API key for sending emailsFormat: key-xxxxxxxxxxxxxxxxxxxxxxxxFind in: Mailgun Dashboard → Settings → API Keys
​
MAILGUN_DOMAIN
string
required
Your verified Mailgun domainExample: mg.yourdomain.com or sandboxxxxx.mailgun.org
​
FROM_EMAIL
string
required
Email address to send from (must use Mailgun domain)Example: [email protected]
​
ADMIN_EMAIL
string
required
Admin email for receiving notificationsExample: [email protected]
​
ADMIN_PHONE_NUMBER
string
Admin WhatsApp number for notificationsFormat: Include country code with +Example: +1234567890
​
NEXT_PUBLIC_SHOW_FOOTER
string
Show or hide footer in applicationDefault: trueOptions: true or false

​
Database Schema Overview

The application uses these main collections:
  • user: User accounts with roles (ADMIN, USER, GUEST)
  • session: Active user sessions with expiry
  • account: Password hashes and OAuth provider data
  • verification: Email verification tokens
  • WhatsAppSession: Connected WhatsApp accounts
    • sessionName: Unique session identifier
    • phoneNumber: Connected phone number
    • status: CONNECTED or DISCONNECTED
  • WhatsAppGroup: Synced WhatsApp groups
    • groupName: Display name
    • groupId: WhatsApp group ID
  • MessageCampaign: Scheduled campaigns
    • title: Campaign name
    • template: Message template with placeholders
    • sendTimeUtc: Scheduled send time
    • status: DRAFT, SCHEDULED, IN_PROGRESS, COMPLETED, CANCELLED, FAILED
  • Message: Individual messages to send
    • content: Processed message content
    • scheduledAt: When to send
    • sentAt: When actually sent
    • isSent: Delivery status

​
Available Scripts

# Start development server (Next.js on port 3001)
pnpm dev

# Start message scheduler
pnpm scheduler:start

# Open Prisma Studio (database GUI)
pnpm db:studio

​
Troubleshooting

Error: @prisma/client did not initialize yetSolution:
# Manually generate Prisma client
pnpm prisma:generate

# If that fails, try
rm -rf node_modules/.prisma
pnpm install
Error: Error connecting to database or ECONNREFUSEDSolutions:
  • Verify DATABASE_URL is correctly formatted
  • For MongoDB Atlas:
    • Whitelist your IP address in Network Access
    • Check username/password are URL-encoded
    • Ensure database user has read/write permissions
  • For local MongoDB:
    • Ensure MongoDB service is running
    • Try mongodb://localhost:27017/whatsapp-manager
Error: Cannot connect to WAHA serverSolutions:
  • Verify WAHA is running: curl http://localhost:3000/health
  • Check WAHA_API_URL points to correct address
  • Verify WAHA_API_KEY matches WAHA configuration
  • Ensure no firewall blocking the connection
Error: Failed to send email or Mailgun errorsSolutions:
  • Verify Mailgun API credentials are correct
  • Check domain is verified in Mailgun dashboard
  • Ensure FROM_EMAIL uses your Mailgun domain
  • For sandbox domain, add recipient email to authorized recipients
Issue: Scheduled messages remain in SCHEDULED statusSolutions:
  • Ensure scheduler is running: pnpm scheduler:start
  • Check scheduler logs for errors
  • Verify scheduled time is in the past (UTC)
  • Check WhatsApp session is CONNECTED
  • Ensure WAHA server is accessible from scheduler
Error: Port 3001 is already in useSolution:
# Find process using port 3001
lsof -i :3001

# Kill the process (replace PID with actual process ID)
kill -9 PID

# Or use a different port
PORT=3002 pnpm dev

​
Security Best Practices

Follow these security guidelines for production deployments:
  • Never commit .env file to version control
  • Use strong, unique secrets for BETTER_AUTH_SECRET in production
  • Rotate API keys regularly (Mailgun, WAHA)
  • Enable MongoDB authentication and use strong passwords
  • Restrict MongoDB network access to your server IPs only
  • Use HTTPS for production deployments (Vercel provides this automatically)
  • Set up IP whitelisting for WAHA if possible
  • Regularly update dependencies with pnpm update
  • Monitor logs for suspicious activity
  • Backup database regularly (MongoDB Atlas has automated backups)

​
Next Steps

After successful installation:

User Guide

Learn how to use the dashboard and manage campaigns

API Documentation

Explore tRPC API endpoints and integration options

Contributing

Contribute to the project on GitHub

Support

Get help and report issues

Build docs developers (and LLMs) love

Get started for freeTalk to us