Troubleshooting

1. Check the number’s status. Open Numbers — the line must show Ready. If it’s connecting, disconnected, or logged_out, fix the connection first (see below).
2. Give history time to sync. Right after linking, Loopwave pulls history in the background over the first couple of minutes. Older chats fill in progressively.
3. Pull older history on demand. If a re-link didn’t bring enough history, use the number’s sync-history action to fetch an older batch.
4. Confirm the database is reachable. If MongoDB is down, the inbox can’t read or store chats. Check MONGODB_URI and that MongoDB is running.
5. Check the browser console / API logs for errors if the list stays empty.

1. Scan within the time limit. QR codes expire; if it times out, refresh to get a new one and scan promptly.
2. Scan from the right place. On the phone holding that number, go to WhatsApp → Settings → Linked Devices → Link a Device.
3. Check linked-device limits. WhatsApp caps how many devices a number can link. Remove an unused linked device on the phone, then try again.
4. Use a clear, well-lit screen. A dim or partially covered QR won’t scan.

1. Keep the phone online. Linked devices need the phone reachable periodically. A phone that’s off or offline will cause drops.
2. Let auto-reconnect work. On a disconnected state, Loopwave retries automatically. Brief drops usually recover on their own.
3. Re-link on logged_out. This means the device was unlinked from the phone side (or removed from WhatsApp’s Linked Devices list). Scan a fresh QR code to reconnect.
4. Verify the data directory persists. If AUTH_DIR was wiped or isn’t writable, credentials are lost and the number must be re-linked. Make sure the directory is persistent and writable.

1. Open the message to trigger download. Loopwave downloads media lazily — the file is fetched the first time it’s opened, then cached.
2. Keep the source number connected. Media is downloaded through a connected session. If the number is offline, the download can’t complete; reconnect and try again.
3. Retry after reconnecting. A media item that failed to download while a number was offline can be re-fetched once it’s ready again.
4. Check disk space. Downloaded media is cached on disk; a full disk will block new downloads.

This is usually intended. Number masking is on by default and hides customer numbers from agents (admins always see them). To change it, an admin can toggle masking in Settings → Privacy.

A 402 means the license is expired, revoked, or invalid and the deployment is in enforce mode, so writes are blocked while reads still work. Open Settings → Billing & License, check the state, and activate or refresh a valid key. See Licensing.

• 401 invalid_api_key: the key is missing, malformed, or disabled. Confirm the header (Authorization: Bearer lw_live_... or X-API-Key) and that the key is enabled.
• 403 insufficient_scope: the key lacks the scope for that endpoint. Add the scope or use a * key. See Authentication.

This is often the anti-ban guards doing their job:

• The sending number must be ready — a disconnected number pauses sends.
• Auto-replies honor a per-chat cooldown, a global rate cap, and skip your own outbound messages and (by default) group chats. See Auto-reply guards.
• Broadcasts send one recipient per tick with randomized delays and a daily cap, so large campaigns take time and may span days by design. See Broadcast pacing.

1. Confirm the webhook is enabled and subscribed to the right events.
2. Send a test delivery from the webhook screen and watch your endpoint.
3. Return a 2xx quickly. Endpoints that time out (5s) or error are retried, then the failure is recorded on the webhook (last status / last error) — check those fields.
4. Verify the signature correctly over the raw body. A mismatch usually means the body was re-serialized before hashing. See Webhooks.