Fix: WhatsApp Bot Keeps Disconnecting
Why your WhatsApp bot session disconnects and how to fix it. Covers QR expiry, 401 auth errors, 428 rate limits, and network issues.
A BotWave session showing "Disconnected" in the dashboard usually self-recovers within a minute, but if it stays disconnected for more than a few minutes, one of four root causes is almost always responsible. This page walks through how to diagnose which one and what to do.
Confirm the symptoms
- Dashboard → Sessions shows a red "Disconnected" badge.
- !help in WhatsApp gets no response.
- WhatsApp shows the linked device but says "Last seen: hours ago" on it.
- Auto-reconnect attempts in the dashboard log are failing in a row.
30-second quick fix
- Open Dashboard → Sessions → click the session → Reconnect.
- If reconnect fails immediately, check that the phone connected to the WhatsApp account is online (you can verify by sending yourself a message from WhatsApp Web).
- If the phone is offline, simply re-opening WhatsApp on the phone usually triggers BotWave to reconnect within 60 seconds.
Root causes
1. Phone offline / WhatsApp closed for too long
BotWave is a Linked Device, it depends on your phone's WhatsApp being awake periodically. If your phone is offline overnight or WhatsApp is force-closed, the linked device disconnects.
- Re-open WhatsApp on the phone.
- Wait up to 60 seconds for auto-reconnect.
- If still disconnected, click Reconnect in the dashboard.
2. WhatsApp Web logout (one-button kill)
If you tap "Log out from all devices" in WhatsApp Settings → Linked Devices, every Linked Device including BotWave is killed. The session must be re-paired from scratch.
- Open BotWave → Sessions → Reconnect with pairing code or QR.
3. Linked-device cap (4 device limit)
WhatsApp allows 4 linked devices simultaneously. If you pair a 5th, WhatsApp silently kicks the oldest, which can include your BotWave session.
- In WhatsApp Settings → Linked Devices, remove old/unused entries.
- Re-pair BotWave.
4. Server-side maintenance or deploy
During a BotWave deploy the session containers briefly restart. Reconnect usually happens automatically within 30s.
- Wait 1-2 minutes; the session reconnects automatically.
Detailed resolution
- 1
Confirm the phone is online
Open WhatsApp on the device that owns the session and send yourself a message via WhatsApp → You → message yourself.
- 2
Click Reconnect in the dashboard
Dashboard → Sessions → click your session → Reconnect.
- 3
Wait 60 seconds
Reconnect handshakes take time. The status will flip to Connected when done.
- 4
If still disconnected, check WhatsApp linked devices
WhatsApp → Settings → Linked Devices. If your BotWave entry is gone, re-pair.
- 5
Re-pair if needed
Use the pairing-code flow. Your custom commands, group config, and analytics are preserved.
Expected result
Dashboard shows green "Connected" badge and !help works again.
Prevent it next time
- Avoid hitting "Log out from all devices" in WhatsApp.
- Keep your phone's WhatsApp open for at least a few seconds per day so the linked device stays warm.
- Don't exceed 4 linked devices.
Frequently asked questions
Will my custom commands and group settings be lost?
No. Session-level config (commands, group rules, warnings, analytics) is stored against your BotWave account, not against the WhatsApp session credentials. Re-pairing keeps everything.
Why does the session disconnect every night?
Phone going offline overnight is the most common cause. If this is consistent, leave the phone charging and WhatsApp open, or upgrade to a sessions-on-server plan (Boss) where the dependency on your phone is reduced.
How long can a session stay disconnected before something bad happens?
Up to ~14 days. Beyond that, WhatsApp's Linked Device entry expires server-side and you must re-pair.
Still stuck?
Open a support ticket from the dashboard and we will look at your session logs directly.
Other troubleshooting guides
WhatsApp Bot Logged Out Automatically
How to fix "WhatsApp Bot Logged Out Automatically". Step-by-step troubleshooting guide with solutions.
Bot Session Needs Re-authentication
How to fix "Bot Session Needs Re-authentication". Step-by-step troubleshooting guide with solutions.
WhatsApp Multi-Device Bot Issue
How to fix "WhatsApp Multi-Device Bot Issue". Step-by-step troubleshooting guide with solutions.