⚙️ Node Gateway Setup

---

The WhatsApp connection is handled by a small Node.js gateway that ships inside the module at Modules/WhatsAppQrLogin/node-gateway. It keeps your WhatsApp numbers connected, sends and receives messages, and pushes live updates to the chat inbox.

You set this up once on your server. After that it runs in the background and reconnects your numbers automatically whenever the server restarts.

⛔ BEFORE YOU START — PLEASE READ

• No shared hosting. You need a VPS or cloud server (e.g. CloudPanel). Shared/cPanel plans won't work.
• Redis is required. The gateway won't start without it.
• Don't use root or sudo for the steps below. Run them as your normal site user (the one that owns your app files). Using root breaks file permissions.

This is a one-time server setup done over SSH by whoever manages your hosting. Your customers never see it — they only scan a QR code from their browser.

What You Need

Before you start, make sure your server has:

• Node.js 20 or higher
• Redis running and reachable (the gateway uses it internally)
• A domain with SSL/HTTPS already set up (e.g. through CloudPanel)

That's it. The gateway reuses your app's existing database and Redis settings automatically, so there's almost nothing to configure by hand.

Step 1 — Install

Open a terminal on your server, go to the gateway folder, and install:

cd Modules/WhatsAppQrLogin/node-gateway
npm install

This downloads everything the gateway needs. It only has to be done once (and again after an update).

Step 2 — Start the Gateway

The gateway comes with a ready-to-use configuration file (node-gateway/.env) that is created automatically the first time the module runs — you don't need to edit it for a normal setup.

To make sure everything works, start it once in the foreground:

cd Modules/WhatsAppQrLogin/node-gateway
npm run dev

Step 3 — Keep It Running

For a live site, the gateway must stay running even after you close the terminal or reboot the server. The easiest way is pm2:

# Install pm2 once, globally
npm install -g pm2

# Start the gateway and keep it alive
cd Modules/WhatsAppQrLogin/node-gateway
pm2 start server.js --name whatsapp-qr-gateway --node-args="--env-file=.env"

# Save it so it restarts automatically on reboot
pm2 save
pm2 startup

That's the whole setup. From here on, pm2 restarts the gateway automatically if it crashes or the server reboots — and the gateway restores all previously connected WhatsApp numbers on its own (no re-scanning needed).

Step 4 — Allow Live Chat (WebSocket over HTTPS)

The chat inbox updates in real time using a WebSocket connection. Because your site runs on HTTPS, the browser needs a secure (wss://) address to reach the gateway. The cleanest way is to route it through your existing domain using CloudPanel, so it reuses the SSL certificate you already have.

1. Open the Vhost editor

In CloudPanel, go to Sites → (your site) → Vhost. This is the site-level configuration for your WhatsMark domain — not a global or server-wide file. Editing it here means the WebSocket automatically reuses the SSL certificate CloudPanel already issued for this site.

2. Add a WebSocket route

Inside that site's existing HTTPS server { … } block, add this location:

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;
}

Save — CloudPanel reloads Nginx for you.

Now the chat inbox connects securely through your own domain — no extra ports to open, no separate certificate to manage.

WHY THIS STEP MATTERS

Without it, messages still send and receive, but the inbox won't update live — you'd have to refresh the page to see new messages. This step is what makes the chat feel instant.

Step 5 — Final Check

Confirm everything is working end to end:

1. As a customer, open the WhatsApp QR page, scan the code, and wait for Connected.
2. Send a test message — it should appear instantly in the inbox (that confirms the WebSocket from Step 4).
3. Watch for the delivery ticks on the message (that confirms sending works).

If anything doesn't work, the Troubleshooting page lists the common symptoms and fixes.

---

With the gateway running, your customers can connect their numbers. Continue to Getting Started for the customer-side flow, or Managing Your Connection for connection statuses and reconnects.