WhatsApp Connection Issues
Fixing QR code expiry, dropped sessions, and other issues specific to the personal-device WhatsApp connection.
The personal-device WhatsApp connection (QR code) works the same way as WhatsApp Web: it links to a session running on your phone, rather than an independent cloud connection. Most connection problems trace back to that dependency. This page covers issues specific to the QR connection — for delivery problems on an otherwise-connected channel, see Message Delivery Issues.
The QR code expired before you scanned it
QR codes are only valid for a short window. If you open the QR screen and don't scan it in time, the code goes stale and scanning it does nothing.
Fix: refresh the QR code on the Gateways screen to generate a new one, then scan it immediately with WhatsApp on your phone (Linked Devices → Link a Device).
The connection shows as disconnected after working fine
Since the QR connection is tied to a live session on your phone, anything that breaks that session breaks the Mersal connection too:
- The phone lost internet access — the linked session needs your phone to stay online, the same as WhatsApp Web does. If your phone is off, in airplane mode, or has no data/Wi-Fi, sending and receiving through that gateway stops until it's back online.
- The phone's battery saver or OS killed the WhatsApp app in the background — some Android battery optimization settings aggressively kill background apps, which can interrupt the session even while the phone is otherwise online.
- WhatsApp was unlinked from the phone itself — if you (or someone with access to the phone) removes the linked device from WhatsApp → Linked Devices on the phone, the session ends immediately from that side, and Mersal's gateway will show as disconnected.
Reconnecting requires a fresh QR scan
If the session was unlinked from the phone's own WhatsApp settings, reconnecting isn't automatic — go back to Gateways in Mersal, generate a new QR code, and scan it again from Linked Devices on the phone.
When to move to the WhatsApp Cloud API instead
The QR connection is genuinely useful — it gets a real WhatsApp channel working in minutes with no Meta Business account required, which is why it's the fastest path for testing or early-stage sending. But because it depends on a personal phone staying powered on and connected, it isn't the right foundation for production traffic you can't afford to interrupt.
If you're seeing repeated disconnections, or you're scaling past what one phone should reasonably handle, move to the WhatsApp Cloud API. It connects through Meta's official embedded signup with a real WhatsApp Business Account, and it doesn't depend on any personal device staying online — it's backed directly by Meta's infrastructure.
See Connecting WhatsApp via QR for the setup walkthrough, and WhatsApp for a full comparison of both connection modes.