Encountering issues with your WhatsApp integration can disrupt your customer support and communication workflows. This comprehensive troubleshooting guide addresses the most common errors you might face when using either the standard WhatsApp Web connection or the WhatsApp Business API on Qpien. We have categorized these issues into connection problems, messaging restrictions, and account status warnings to help you quickly identify, understand, and resolve the root cause.

The QR Code Fails to Scan or Times Out (Standard WhatsApp)

When setting up a standard WhatsApp connection, Qpien generates a QR code that acts as a secure login credential. For security purposes, this code is dynamic and expires very quickly (typically within 10 to 20 seconds).

The most common cause is a delay in scanning the code. If you wait too long after opening the setup page, the code will become invalid. Alternatively, a weak internet connection on either your computer or your mobile device can prevent the scan from registering.

• Check the internet connection on your mobile phone to ensure it is stable.

• Refresh the Qpien setup page to generate a fresh, active QR code.

• Immediately open your WhatsApp mobile app Linked Devices>Link a Deviceand scan the new code.

• Ensure that the phone number you registered in the Qpien setup form exactly matches the phone number of the device you are using to scan the code. A mismatch will cause the connection to fail silently.

This number is registered to an existing WhatsApp account (WhatsApp Business API)

Meta enforces a strict rule: a single phone number cannot be simultaneously active on the standard WhatsApp mobile app (or WhatsApp Business app) and the WhatsApp Business API.

You must completely disconnect and delete the account from the mobile application before API routing can take over.

• Open the WhatsApp or WhatsApp Business app on your mobile device.

• Navigate to Settings>Account>Delete Account.

• Follow the on-screen prompts to permanently delete the account from the mobile app.

• Wait a few minutes, then return to Qpien and retry the API connection process. Your number is now free to be assigned to the API.

If used with a mobile WhatsApp app:
Follow the steps under the Learn more link shown in the error to disconnect the number from that WhatsApp account, then you should be able to retry our onboarding process successfully.

Note: Disconnecting a WhatsApp account deletes chat history unless backed up.

If neither applies, contact Support with your:

• WhatsApp Account ID

• Phone number

We can attempt a manual connection.

Cannot Send Messages / "Message Failed to Send" (The 24-Hour Rule)

If you are using the WhatsApp Business API, you might notice that the message input box is disabled, or a message you attempt to send immediately fails with an error regarding the customer window.

Meta implements a strict "24-Hour Customer Service Window" to prevent businesses from spamming users. This window opens the moment a customer sends you a message. If exactly 24 hours pass without a new incoming message from that customer, the window closes. You are no longer permitted to send standard, free-form text messages.

To initiate a new conversation or reply to a customer outside of this active 24-hour window, you must use a pre-approved WhatsApp Template Message.

• Select a relevant template from your approved list in Qpien.

• Send the template to the customer.

• Once the customer replies to your template, a new 24-hour window opens, and you can resume normal typing and sending free-form messages.

If you haven't created a template yet or don't know it, see Create Whatsapp message templates.

Template Message Rejected or Not Delivered

Sometimes, a template message fails to send, even if you are trying to contact a customer outside the 24-hour window.

This usually stems from two issues: either the template has not been approved by Meta, or there is a billing issue preventing the paid message from being dispatched.

• Check Approval Status: Verify in your Meta Business Manager (or your Gupshup dashboard) that the specific template has a status of "Approved". Meta regularly rejects templates that use overly aggressive promotional language or violate their commerce policies.

• Check Account Balance: If the template is approved but fails to send on a Gupshup Partner API connection, check your Qpien wallet balance. Template messages incur a per-message fee, and if your Qpien balance is zero or insufficient, the message will not be delivered.

Phone Number Banned (Standard WhatsApp)

If you are using the standard WhatsApp Web connection on Qpien for bulk messaging, you might suddenly find that all messages fail and your number is logged out.

Standard WhatsApp accounts are designed for personal use or low-volume business communication. If you send a high volume of identical messages (bulk messaging), or if multiple customers block and report your number as spam, WhatsApp's automated systems will permanently or temporarily ban your phone number.

Qpien cannot unban standard WhatsApp numbers, as this is controlled entirely by Meta's mobile app policies.

• Open the WhatsApp mobile app. You will see a message stating your number is banned.

• Tap Supportor go to Settings>Help>Contact Us.

• Write a polite appeal explaining that you are a legitimate business communicating with your customers.

• To prevent this from happening again, we strongly advise upgrading to the WhatsApp Business API, which is officially designed and approved for high-volume and bulk messaging campaigns.

Number Status Changed to "Flagged" or "Restricted" (Business API)

Even on the official API, Meta monitors the quality of your messaging.

If users frequently block or report your API messages, your phone number's quality rating will drop from "High" (Green) to "Medium" (Yellow) or "Low" (Red). If it drops too low, the status becomes "Flagged", and Meta may impose messaging limits.

Stop any ongoing bulk messaging campaigns immediately. Review your template messages to ensure they are relevant and expected by the recipients. Ensure customers have explicitly opted-in to receive messages from you. As you send higher-quality messages that are not reported, your quality rating will naturally improve over a few days.