Quick Start Guide

Get up and running with WhatsApp WAHA Dashboard in under 10 minutes

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:

   npm

   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:[e-mail]/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="[e-mail]"
   
   # Admin Configuration
   ADMIN_EMAIL="[e-mail]"
   ADMIN_PHONE_NUMBER="[phone]"
   

   How to get these credentials

   • 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

   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

   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:

Check Database Connection

Run Prisma Studio to view your database:

pnpm db:studio

You should see your user account in the database at http://localhost:5555

Verify WhatsApp Connection

In the dashboard, check that:

• Your session shows as CONNECTED
• Your WhatsApp groups are visible
• Session information displays correctly

Test Notifications

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

Port 3000 is already in use

If port 3000 is occupied, you can change it:

PORT=3001 pnpm dev

Remember to update BETTER_AUTH_URL in your .env file.

Prisma Client errors

If you see Prisma Client errors, regenerate the client:

pnpm prisma:generate

WhatsApp won't connect

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

Database connection failed

• 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:

• Check the GitHub Issues
• Review the Installation Guide for detailed setup
• Join our community discussions
• Contact the maintainer @jevil25