User Management

Managing users, approving registrations, and configuring role-based access control

Overview

The WhatsApp WAHA Dashboard includes a comprehensive user management system with role-based access control. Administrators can approve new users, manage permissions, and maintain security across the platform.

User Roles

The system supports three distinct user roles:

GUEST

Pending Approval

New registrations start as GUEST. Limited access until approved by admin.

USER

Standard Access

Can create campaigns, manage groups, and access core features.

ADMIN

Full Access

Complete control over users, campaigns, sessions, and system settings.

Registration & Approval Flow

How User Registration Works

1. User Signs Up

   New users create an account with:

   • Full name
   • Email address
   • Password (minimum 8 characters)

   Account is created with GUEST role automatically.

2. Admin Notification

   Administrators receive notifications via:

   • WhatsApp - Sent to ADMIN_PHONE_NUMBER (if configured)
   • Email - Sent to ADMIN_EMAIL

   If WhatsApp notification fails, the system automatically falls back to email notification.

3. Admin Reviews Request

   Administrators see pending users in the Admin Dashboard.

4. Approval Decision

   Admin can:

   • Approve - Upgrade to USER role
   • Reject/Delete - Remove the account
   • Keep Pending - Leave as GUEST for later decision
5. User Gets Access

   Once approved, user can log in and access the full dashboard.

Admin Dashboard

Accessing the Admin Panel

Administrators can access the admin dashboard at /admin or through the navigation menu.

Admin Dashboard Sections

The admin panel provides comprehensive oversight:

Pending Users

View and manage pending registrations:

• User name and email
• Registration date
• Quick approve/reject actions
• Bulk operations (coming soon)

Available Actions:

• Approve user (promote to USER role)
• Delete user (permanently remove)

Approved Users

Manage active users:

• All users with USER or ADMIN roles
• User details and join dates
• Role management options

Available Actions:

• Promote to ADMIN
• Revoke access (demote to GUEST)
• Delete user

WhatsApp Sessions

Monitor connected WhatsApp accounts:

• Session names and IDs
• Connection status
• Associated groups count
• Last activity timestamp

Available Actions:

• View session details
• Restart sessions
• Monitor connection health

Active Campaigns

Oversee all scheduled campaigns:

• Campaign titles and targets
• Start and end dates
• Status and progress
• Target groups

Available Actions:

• View campaign details
• Monitor message delivery
• Review campaign analytics

WhatsApp Groups

Manage all connected groups:

• Group names and IDs
• Associated campaigns
• Session information

Available Actions:

• View group details
• See campaign history

Managing Users

Approving New Users

1. Navigate to Pending Users

   In the Admin Dashboard, click on the “Pending Users” tab.

2. Review User Details

   Examine:

   • User name
   • Email address
   • Registration date
3. Approve the User

   Click the “Approve” button next to the user’s name.

   The system will:

   • Update user role from GUEST to USER
   • Grant access to dashboard features
   • Remove from pending list

Promoting Users to Admin

Be cautious when granting admin privileges. Admins have full system access including user deletion and system configuration.

1. Find the User

   Navigate to “Approved Users” tab.

2. Click Promote

   Select “Make Admin” or “Promote to Admin” option.

3. Confirm Action

   Verify the promotion and confirm.

Revoking User Access

To temporarily revoke access without deleting the account:

1. Locate User

   Find the user in the “Approved Users” list.

2. Revoke Access

   Click “Revoke Access” button.

   This will:

   • Demote user to GUEST role
   • Block access to dashboard features
   • Preserve user data and campaigns

Revoked users can be re-approved later without losing their data.

Deleting Users

User deletion is permanent and cannot be undone. All associated campaigns will be affected.

1. Select User

   Find the user you want to delete.

2. Click Delete

   Select the delete option.

3. Confirm Deletion

   Confirm the permanent deletion.

   Note: Cannot delete users with ADMIN role for safety.

Adding Users Directly (Admin)

Admins can create pre-approved user accounts:

1. Click Add User

   In the Admin Dashboard, find the “Add New User” button.

2. Fill User Details

   Enter:

   • Full name
   • Email address
   • Password (minimum 8 characters)
3. Create Account

   Submit the form.

   The user will be created with:

   • USER role (pre-approved)
   • Email verification not required
   • Immediate dashboard access

Notification Configuration

Email Notifications

Configure email notifications in your .env file:

# Mailgun Configuration
MAILGUN_API_KEY="your-mailgun-api-key"
MAILGUN_DOMAIN="your-domain.com"
FROM_EMAIL="[e-mail]"

# Admin Configuration
ADMIN_EMAIL="[e-mail]"

WhatsApp Notifications

Enable WhatsApp notifications for new registrations:

# Admin WhatsApp (optional)
ADMIN_PHONE_NUMBER="[phone]"

Include country code with the plus sign. Format: [phone]

Notification Types

Admins receive notifications for:

• New User Registrations - Both WhatsApp and email
• Password Changes - Email only (security)
• System Alerts - Email (critical issues)

Notification Fallback

The system implements a smart fallback strategy:

// Attempt WhatsApp notification
try {
  await sendWhatsAppNotification(adminPhone, message);
} catch (error) {
  // Fallback to email if WhatsApp fails
  await sendEmailNotification(adminEmail, message);
}

Security Best Practices

Verify Users

Always verify user identity before approval, especially for sensitive organizations.

Limit Admins

Only promote trusted users to ADMIN role. Minimize the number of administrators.

Regular Audits

Periodically review user list and revoke access for inactive or departed users.

Strong Passwords

Enforce strong password requirements (8+ characters, complexity).

Monitor Activity

Regularly check campaign creation and message sending patterns.

Email Verification

Consider implementing email verification for additional security.

Role Permissions Matrix

Feature	GUEST	USER	ADMIN
View Dashboard	❌	✅	✅
Connect WhatsApp	❌	✅	✅
View Groups	❌	✅	✅
Create Campaigns	❌	✅	✅
Edit Own Campaigns	❌	✅	✅
Delete Own Campaigns	❌	✅	✅
View Admin Dashboard	❌	❌	✅
Approve Users	❌	❌	✅
Manage All Users	❌	❌	✅
View All Campaigns	❌	❌	✅
View All Sessions	❌	❌	✅
System Configuration	❌	❌	✅

Troubleshooting

Admin Notifications Not Received

Check these items:

1. Email notifications:
   • Verify MAILGUN_API_KEY is correct
   • Check ADMIN_EMAIL is set
   • Review Mailgun dashboard for delivery status
   • Check spam folder
2. WhatsApp notifications:
   • Verify ADMIN_PHONE_NUMBER format ([phone])
   • Ensure WhatsApp session is connected
   • Check WhatsApp session has permission to message admin
3. Logs:
   # Check application logs
   pm2 logs your-app-name
   

Cannot Delete User

Common causes:

1. User is ADMIN - Cannot delete admin users for safety
2. Database constraint - User has associated campaigns

Solutions:

• For admins: First demote to USER, then delete
• For users with campaigns: Campaigns will be orphaned (feature update needed)

User Can't Access After Approval

Troubleshooting steps:

1. Verify user role changed to USER in database
2. Ask user to log out and log back in
3. Clear browser cache and cookies
4. Check for errors in browser console
5. Verify session is valid

Cannot Access Admin Dashboard

Verify:

1. User role is ADMIN (not USER or GUEST)
2. Check database: db.user.findUnique({ where: { email: '[e-mail]' }})
3. Clear authentication cookies
4. Restart application if roles were recently changed

API Reference

Key admin API endpoints (tRPC procedures):

User Management

// Get pending users
adminRouter.getPendingUsers()

// Get approved users
adminRouter.getApprovedUsers()

// Approve user
adminRouter.approveUser({ userId: string })

// Revoke access
adminRouter.revokeAccess({ userId: string })

// Delete user
adminRouter.deleteUser({ userId: string })

// Add new user
adminRouter.addNewUser({ 
  name: string, 
  email: string, 
  password: string 
})

// Promote to admin
adminRouter.makeAdmin({ userId: string })

System Monitoring

// Get WhatsApp sessions
adminRouter.getWhatsAppSessions()

// Get WhatsApp groups
adminRouter.getWhatsAppGroups()

// Get active campaigns
adminRouter.getActiveCampaigns()

Next Steps

Setup WhatsApp

Connect WhatsApp accounts for your users

Create Campaigns

Start creating message campaigns