🛠️ Troubleshooting

---

This page collects fixes for the issues we see most often. If your problem isn't listed, check the FAQ or contact support via your CodeCanyon item page.

8.1 The QR Code Expires Before I Can Scan It

QR codes are valid for about 60 seconds — this is enforced by WhatsApp itself, not the module. The fix:

1. Click Refresh on the connection page — a new QR appears.
2. Make sure your phone's camera is unlocked and ready before you click Refresh.
3. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device ahead of time so you're already on the camera screen.

📷 BE READY BEFORE YOU REFRESH

Most expired-QR situations come from opening WhatsApp and navigating to the camera after clicking Refresh. Have the phone ready first.

8.2 "Connection Failed" Right After I Scan

If the page jumps from Connecting straight to Failed after a successful scan:

• Make sure your phone's WhatsApp is up to date (open the app store and check for updates).
• Try again on a stable network — avoid VPNs or restrictive Wi-Fi while scanning.
• If the same error keeps coming up, delete the connection and start a fresh one.
• If that still doesn't work, contact your administrator — they may need to check the gateway service is running and reachable.

8.3 Messages Stay on "Pending"

Pending normally lasts only a second or two. If a message stays pending:

• For more than a minute, it usually clears on its own.
• For more than 10 minutes, the system marks it as Failed. You can retry by sending again.
• If every message in every chat stays pending, your connection is most likely offline — go to the Connection page and check the status. Click Reconnect if it's not showing Connected.

8.4 The Chat List Shows Old Messages but Nothing New Arrives

This usually means the WebSocket connection between your browser and the gateway has silently dropped.

1. Refresh the page once.
2. If new messages still don't flow, your connection may have silently dropped on the gateway side — go to the Connection page and click Reconnect.
3. If reconnecting succeeds but new messages still don't appear, ask your administrator to verify the gateway service is healthy (/health endpoint).

8.5 Voice Notes Won't Record

The browser needs microphone permission for the page.

1. Look for a microphone icon in your address bar — click it and allow access for this site.
2. Reload the page so the new permission takes effect.
3. Try Chrome or Edge if recording fails in another browser — they have the most reliable WebRTC microphone support.
4. If you're on macOS, also check System Preferences → Security & Privacy → Microphone and make sure your browser is allowed.

8.6 Media Files Won't Upload

If image, video, audio, or document attachments fail:

• Check the file size — see Limits & Quotas for the caps. Files above WhatsApp's limits are silently rejected.
• Check the file type — for example, .heic photos from iPhones must be converted to JPG/PNG first.
• Make sure your HTTPS certificate is valid — browsers refuse to upload large files from pages with broken SSL.

8.7 My Number Got Banned

If WhatsApp bans the connected number, no third-party tool can recover it — the ban is on WhatsApp's side.

To avoid being banned in the first place:

• Don't send unsolicited messages to people who don't know you — that's the #1 way numbers get reported as spam.
• Spread sends out over the day — the built-in throttle is there for a reason; don't ask your administrator to remove it.
• Make sure your message templates feel personal, not robotic. Use merge fields, vary the wording, don't paste the exact same message 200 times.

🚫 NO RECOVERY FROM A FULL BAN

A fully-banned number cannot be restored by the module, by Corbital, or by anyone other than Meta. Start fresh with a new SIM and warm it from day 1. Treat ban prevention as a hard requirement, not an optimisation.

8.8 The Gateway Health Check Fails

If /health on the gateway returns a non-200 status or times out:

1. SSH into the gateway host and check the process is running (pm2 status or systemctl status).
2. Tail the gateway logs and look for crash traces or database connection errors.
3. Verify the database credentials in the gateway .env are correct and the database is reachable.
4. Restart the gateway and watch the logs for clean startup messages.

8.9 WebSocket Doesn't Upgrade Behind nginx / Apache

If chats don't update live but sending works:

• Confirm your reverse proxy is configured to forward WebSocket upgrades. For nginx, the proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade" directives are required (see the snippet in the Installation Guide).
• If you're behind Cloudflare, make sure the gateway endpoint isn't on a "Lite" plan that strips WebSocket upgrades.

---

If your issue persists after all of the above, contact support via the CodeCanyon item page with: a description of what you tried, your gateway log output around the time of the issue, and the connection status as shown in the dashboard.