Skip to main content

​
Overview

This quick start guide will help you get WhatsApp WAHA Dashboard up and running in your local development environment. You’ll set up your database, connect to WAHA, and create your first campaign.
This guide assumes you have basic familiarity with Node.js and command-line tools. For detailed installation instructions, see the Installation Guide.

​
Prerequisites

Before starting, ensure you have:

Node.js 18+

Download from nodejs.org

pnpm

Install with npm install -g pnpm

MongoDB

Local instance or MongoDB Atlas account

WAHA Server

WhatsApp HTTP API server running
You must have a running WAHA (WhatsApp HTTP API) server before you can use this dashboard. WAHA handles the WhatsApp connection and message delivery.

​
Quick Setup

1

Clone and Install

Clone the repository and install dependencies:
git clone https://github.com/jevil25/whatsapp-waha-dashboard.git
cd whatsapp-waha-dashboard
npm install
2

Configure Environment

Create a .env file in the root directory with the following configuration:
# Database
DATABASE_URL="mongodb+srv://username:[email protected]/whatsapp-manager"

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

# Better Auth
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"

# Mailgun (for email notifications)
MAILGUN_API_KEY="your-mailgun-api-key"
MAILGUN_DOMAIN="your-mailgun-domain"
FROM_EMAIL="[email protected]"

# Admin Configuration
ADMIN_EMAIL="[email protected]"
ADMIN_PHONE_NUMBER="+1234567890"
  • DATABASE_URL: Get from MongoDB Atlas or use local MongoDB
  • WAHA_API_KEY: Set in your WAHA server configuration
  • BETTER_AUTH_SECRET: Generate with openssl rand -base64 32
  • MAILGUN credentials: Sign up at mailgun.com
3

Initialize Database

Generate the Prisma client and push the schema to your database:
npm run prisma:generate
npm run db:push
This will create all necessary tables in your MongoDB database based on the Prisma schema.
4

Start Development Server

Launch the Next.js development server:
npm run dev
The application will be available at http://localhost:3000
5

Create Your Admin Account

  1. Open http://localhost:3000/auth
  2. Click Sign Up and create an account
  3. Use the email address you configured as ADMIN_EMAIL
  4. Complete the registration form
The first user with the admin email will automatically receive ADMIN privileges. All other users start as GUEST and require approval.
6

Connect WhatsApp

  1. Log in to your dashboard
  2. Navigate to the WhatsApp connection section
  3. Click Connect WhatsApp
  4. Scan the QR code with your WhatsApp mobile app:
    • Open WhatsApp → Settings → Linked Devices → Link a Device
  5. Wait for the connection to establish
Keep your phone connected to the internet during the QR code scan process.

​
Verify Your Setup

After completing the setup, verify everything is working:
Run Prisma Studio to view your database:
pnpm db:studio
You should see your user account in the database at http://localhost:5555
In the dashboard, check that:
  • Your session shows as CONNECTED
  • Your WhatsApp groups are visible
  • Session information displays correctly
If configured, you should receive:
  • Admin notification when new users register
  • Email confirmation for password changes

​
Create Your First Campaign

Now that everything is set up, create your first message campaign:
1

Navigate to Campaign Creation

From the dashboard, click Create Campaign or Schedule Message
2

Select Target Group

Choose a WhatsApp group from your connected groups
3

Compose Message

Write your message. You can use placeholders like {days_left} for dynamic content
4

Schedule Delivery

Set the date and time for message delivery, including timezone
5

Submit Campaign

Review and submit your campaign. It will automatically send at the scheduled time!

​
Next Steps

Setup Message Scheduler

Deploy the background scheduler for automatic message delivery

User Management

Learn how to manage user registrations and permissions

Campaign Features

Explore advanced campaign management features

Deploy to Production

Deploy your application to Vercel

​
Troubleshooting

If port 3000 is occupied, you can change it:
PORT=3001 pnpm dev
Remember to update BETTER_AUTH_URL in your .env file.
If you see Prisma Client errors, regenerate the client:
pnpm prisma:generate
Common solutions:
  • Verify WAHA server is running
  • Check WAHA_API_URL and WAHA_API_KEY are correct
  • Ensure your phone has internet connection
  • Try restarting the WAHA server
  • Verify your MongoDB instance is running
  • Check DATABASE_URL format is correct
  • For MongoDB Atlas, ensure your IP is whitelisted
  • Test connection with pnpm db:push

​
Getting Help

If you encounter issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us