Docs / Waziper
Signup

Install WhatsApp Server

Deploy whatsapp_server.zip and connect it to Waziper.

Estimated reading: 4 minutes

Install WhatsApp Server

Purpose

  • The WhatsApp server is required for WhatsApp Unofficial QR login, profile sessions, group listing, message sending, live chat, automation, reports, and REST API actions.
  • Without the Node server, the Laravel app can load, but WhatsApp connection features will not work.

Recommended server layout

  • Install the Laravel application on your main domain, for example https://yourdomain.com.
  • Install the WhatsApp server in a separate folder outside the public web root, for example /home/user/waziper-wa-server.
  • Expose the WhatsApp server through an API domain or subdomain, for example https://wa-api.yourdomain.com.
  • Use HTTPS for the API domain so browser requests, webhooks, and admin API tests are not blocked by mixed-content rules.

Extract whatsapp_server.zip

  • Upload whatsapp_server.zip to the server.
  • Extract it into the WhatsApp server folder.
  • Open the folder in SSH or terminal.
  • Check the main server file name. In most packages it is app.js, server.js, or index.js.
  • If node_modules is not included, run npm install.

Configure environment

  • Open the environment or config file included in the WhatsApp server package.
  • Set the listening port, for example 8000 or 3000.
  • Set the access token or API key used by Waziper.
  • Set any session/storage path if the package supports it.
  • Keep the token private. Do not publish it in documentation, screenshots, or public repositories.

Connect by API domain

  • Create a subdomain such as wa-api.yourdomain.com.
  • Point the subdomain to the same VPS.
  • Configure Nginx, Apache proxy, aaPanel reverse proxy, CloudPanel reverse proxy, or your hosting panel proxy to forward the API domain to the Node server port.
  • Example target: http://127.0.0.1:8000.
  • Enable SSL for the API domain.
  • In Waziper admin settings or API integration settings, set the WhatsApp server URL to https://wa-api.yourdomain.com and enter the same access token configured in the Node server.

Nginx reverse proxy example

  • server_name wa-api.yourdomain.com;
  • proxy_pass http://127.0.0.1:8000;
  • proxy_http_version 1.1;
  • proxy_set_header Upgrade $http_upgrade;
  • proxy_set_header Connection "upgrade";
  • proxy_set_header Host $host;
  • proxy_set_header X-Real-IP $remote_addr;
  • proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  • proxy_set_header X-Forwarded-Proto $scheme;

Apache reverse proxy notes

  • Enable proxy, proxy_http, proxy_wstunnel, headers, and rewrite modules where required.
  • Proxy the API domain to http://127.0.0.1:8000.
  • If your hosting panel has a reverse proxy UI, use it instead of editing Apache config manually.

Run with PM2

  • PM2 is the recommended production process manager because it restarts the server after crashes and reboot.
  • Install PM2 globally with npm install -g pm2.
  • Start the server with pm2 start app.js --name waziper-whatsapp-server. Replace app.js with the actual main file if different.
  • Save the process list with pm2 save.
  • Enable startup with pm2 startup and follow the command it prints.
  • Check logs with pm2 logs waziper-whatsapp-server.

Run with cron instead of PM2

  • If PM2 is not available, use cron as a watchdog that starts the Node server when it is not running.
  • Create a small shell script such as /home/user/waziper-wa-server/start-wa-server.sh.
  • The script should cd into the WhatsApp server folder, check whether the Node process is already running, and start it in the background only if it is missing.
  • Add a cron entry that runs every minute.
  • Cron watchdog is less reliable than PM2, but it works on servers where background process managers are restricted.

Cron watchdog example

  • #!/bin/bash
  • APP_DIR="/home/user/waziper-wa-server"
  • APP_FILE="app.js"
  • APP_NAME="waziper-whatsapp-server"
  • cd "$APP_DIR" || exit 1
  • pgrep -f "$APP_DIR/$APP_FILE" >/dev/null 2>&1 && exit 0
  • nohup node "$APP_FILE" >> "$APP_DIR/wa-server.log" 2>&1 &

Cron entry example

* * * * * /bin/bash /home/user/waziper-wa-server/start-wa-server.sh >/dev/null 2>&1

Windows development example

  • For local Windows testing, open PowerShell in the WhatsApp server folder.
  • Run npm install if needed.
  • Start with node app.js, replacing app.js with the actual main file.
  • For production on Windows Server, use a service manager such as NSSM or Task Scheduler instead of keeping a terminal open.

Validate the connection

  • Open the API domain in a browser or use curl to confirm it responds.
  • Open Waziper -> Admin Dashboard -> Settings or API Integration and save the WhatsApp server URL and token.
  • Open Waziper -> WhatsApp REST API.
  • Generate or select an instance ID.
  • Request a QR code.
  • Scan the QR code with WhatsApp and confirm the profile becomes connected.
  • Send a test direct message to your own number before using campaigns.

Common connection problems

  • API domain returns 502: Node server is not running or reverse proxy points to the wrong port.
  • QR does not load: token mismatch, API URL mismatch, mixed HTTP/HTTPS content, or firewall block.
  • Session disappears after restart: WhatsApp server session folder is not writable or was deleted.
  • Webhook does not trigger: wrong APP_URL, wrong API domain, SSL problem, or firewall issue.
  • Cron starts many Node processes: the watchdog process check is wrong. Fix pgrep or process matching before enabling cron.