🚀 WhatsApp QR Login Module Installation Guide

---

Important Notice

This module requires the latest version of WhatsMarkSaaS and MySQL 8.* or higher. The bundled Node.js gateway service must be running and reachable from your application server.

Prerequisites

Before installing the WhatsApp QR Login Module, make sure you have:

• WhatsMarkSaaS (latest version) installed and running
• PHP 8.1 or higher
• MySQL 8.* or higher database server
• Node.js 18+ available on the host that will run the gateway service
• Valid SSL certificate on your domain
• Public URL (the gateway needs a stable, reachable host — localhost is not supported)
• Admin access to your WhatsMarkSaaS dashboard
• A WhatsApp account on a phone ready to scan the QR

💡 PRO TIP

Have the phone with the WhatsApp account you want to connect ready before you start — the QR codes expire after about 60 seconds, so it pays to be prepared.

---

Installation Steps

For downloading, uploading, activating, and licensing the module, follow the general Module Setup guide.

You'll also receive the Node.js gateway service and documentation in the same zip file — extract it alongside the module, keeping the separate gateway/ folder for the Node.js service.

🔑 IMPORTANT

Keep your purchase code secure. Sharing your purchase code can result in your license being blacklisted. Each purchase code is valid for only one production installation.

Deploy & Run the Gateway Service

The QR Login module relies on a small Node.js gateway service (bundled at Modules/WhatsAppQrLogin/node-gateway) that maintains the WhatsApp Web connection on your server. In brief:

1. Run npm install inside Modules/WhatsAppQrLogin/node-gateway
2. Set any gateway-specific overrides in node-gateway/.env (a starter file is created for you)
3. Start the service under a process manager (e.g. pm2 start server.js --name whatsapp-qr-gateway)
4. Make sure the gateway (HTTP 3010) and WebSocket (3011) are reachable over HTTPS

🟢 FULL GATEWAY GUIDE

The gateway has its own dedicated page covering Redis, the BullMQ send queue, WebSocket SSL, and the queue dashboard. See Node Gateway Setup & Configuration for the complete walkthrough. A GET /health returning 200 OK confirms the gateway is up.

Configure Plan Features

After successful installation:

• Navigate to Admin > Plans & Pricing
• Edit the subscription plans that should include WhatsApp QR Login
• Find the WhatsApp QR Login feature textbox and enter 1 to enable it (or 0 to disable)
• Save the plan configuration

📋 PLAN CONFIGURATION EXAMPLE

Here's a typical configuration for enabling WhatsApp QR Login on a plan:

1. Go to Admin > Plans & Pricing
2. Select the plan you want to update (e.g. "Professional" or "Enterprise")
3. Find the Features or Modules section
4. Locate the WhatsApp QR Login feature textbox
5. Enter 1 to enable the feature (or 0 to disable)
6. Save the changes
7. Repeat for other plans as needed

Post-Installation Requirements

🌐 ENVIRONMENT REQUIREMENT

The module requires a production environment with a valid public domain and SSL certificate. Localhost or local development environments are not supported, because the WebSocket and media upload endpoints must be reachable from the user's browser.

Server Requirements

• Node.js 18+ for the gateway service
• HTTPS / SSL — required for live chat WebSocket and media uploads
• WebSocket support — make sure your reverse proxy (nginx, Apache, Caddy) is configured to upgrade WebSocket connections
• Public URL — localhost is not supported

Reverse Proxy WebSocket Hint

If you use nginx in front of the gateway, make sure your location block forwards WebSocket upgrades:

location /qr-ws/ {
    proxy_pass http://127.0.0.1:3011/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

For the full step-by-step WebSocket setup (including how to do it in CloudPanel), see the Node Gateway Setup page.

First Connection Test

Once installation is complete, test the module end-to-end:

1. Log in as a tenant on a plan that has QR Login enabled
2. Open the WhatsApp QR Login page from the menu
3. Click New Connection, give it a name, and scan the QR with your phone
4. Wait for the status to turn Connected — your phone number and WhatsApp display name should appear
5. Click Open Chats and send a test message

If the QR doesn't appear, the connection fails, or messages don't flow, see the Troubleshooting page.

Next Steps

Once installation is complete:

1. Configure plan features — enable WhatsApp QR Login on the right subscription plans
2. Tenant onboarding — guide tenants through their first QR scan
3. Read the Chat Interface guide — learn the inbox, composer, and message types

For detailed configuration steps, refer to the Getting Started Guide.