Skip to main content

​
Overview

The WhatsApp WAHA Dashboard connects to your WhatsApp account through the WAHA (WhatsApp HTTP API) server. This guide will walk you through the entire setup process, from configuring WAHA to scanning the QR code and verifying your connection.

​
Prerequisites

Before you begin, ensure you have:
  • A WhatsApp account on your mobile device
  • Access to the WAHA server (local or hosted)
  • WAHA API credentials (API URL and API Key)
  • Administrator access to configure environment variables

​
Setting Up WAHA Server

​
Environment Configuration

First, configure your WAHA connection in the .env file: 
# WhatsApp API Configuration
WAHA_API_URL="http://localhost:3000"
WAHA_API_KEY="your-waha-api-key"
If you’re using a hosted WAHA instance, replace localhost:3000 with your WAHA server URL.

​
WAHA Server Options

You have several options for running WAHA:
  1. Local Docker Installation - Run WAHA on your local machine
  2. Cloud Hosted - Deploy WAHA to a VPS or cloud provider
  3. Managed Service - Use a managed WAHA hosting service
For production use, we recommend hosting WAHA on a reliable server to ensure 24/7 availability for message scheduling.

​
Connecting Your WhatsApp Account

1

Navigate to Dashboard

Log in to your WAHA Dashboard account and navigate to the main dashboard page.
2

Initiate Connection

Look for the “Connect WhatsApp” button or WhatsApp session section. Click to start the connection process.
3

Generate QR Code

The system will communicate with your WAHA server to generate a unique QR code for authentication.
4

Scan QR Code

Using your WhatsApp mobile app:
  1. Open WhatsApp on your phone
  2. Tap Settings (or Menu on Android)
  3. Select Linked Devices
  4. Tap Link a Device
  5. Point your camera at the QR code on screen
5

Verify Connection

Once scanned successfully, your WhatsApp session will appear as “CONNECTED” in the dashboard.

​
Understanding WhatsApp Sessions

​
Session Status

Your WhatsApp session can have different statuses:
  • CONNECTED - Active and ready to send messages
  • DISCONNECTED - Session is not active
  • FAILED - Connection error occurred

​
Session Management

The dashboard provides real-time session monitoring with:
  • Auto-refresh capabilities to check connection status
  • Manual restart options when issues occur
  • Session metadata including creation date and last update

​
Viewing Connected Groups

Once connected, the system automatically syncs your WhatsApp groups:
1

Access Groups View

Navigate to the WhatsApp Groups section in the dashboard.
2

Review Group List

You’ll see all your WhatsApp groups with:
  • Group names
  • Group IDs
  • Associated campaigns
  • Search and pagination capabilities
3

Select Target Groups

Use the search functionality to find specific groups when creating campaigns.

​
Troubleshooting

Possible causes:
  • WAHA server is not running
  • Incorrect WAHA_API_URL in environment variables
  • Network connectivity issues
Solutions:
  1. Verify WAHA server is running: curl http://your-waha-url/health
  2. Check environment variables in .env file
  3. Ensure firewall allows connection to WAHA server
  4. Review application logs for detailed error messages
Possible causes:
  • Unstable internet connection
  • WAHA server restarts
  • WhatsApp Web session limits
Solutions:
  1. Ensure WAHA server has stable internet connection
  2. Use process manager (PM2) to keep WAHA running
  3. Limit number of linked devices on your WhatsApp account
  4. Use the manual restart feature in the dashboard
Possible causes:
  • Session not fully synchronized
  • API permission issues
  • Groups created after connection
Solutions:
  1. Refresh the session in the dashboard
  2. Disconnect and reconnect WhatsApp
  3. Verify WAHA API key has proper permissions
  4. Wait a few moments for sync to complete
Possible causes:
  • Incorrect WAHA_API_KEY in environment variables
  • API key expired or revoked
Solutions:
  1. Verify the API key in your .env file matches your WAHA server configuration
  2. Generate a new API key from your WAHA server
  3. Restart the application after updating environment variables

​
Best Practices

Keep WAHA Running

Use a process manager like PM2 to ensure your WAHA server stays online 24/7.

Monitor Connection

Regularly check your session status in the admin dashboard to catch issues early.

Secure Your API Key

Never commit your WAHA_API_KEY to version control. Use environment variables.

Plan for Restarts

Sessions may need occasional restarts. Use the dashboard’s restart feature when needed.

​
Next Steps

Now that your WhatsApp is connected, you can:

Create Campaigns

Learn how to create and schedule message campaigns

Manage Users

Set up user access and permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us