🟢 How to Solve Common Errors When Connecting a WhatsApp Account in BotCommerce

📚 Learn how to fix the most common WhatsApp connection errors in BotCommerce, from account eligibility issues to portfolio verification.

If you’re experiencing issues connecting your WhatsApp account to BotCommerce, you’re not alone. This article will walk you through the most common error messages and explain what causes them, how to fix them, and what steps you can take to move forward.

“User cannot be added to business”

This error usually occurs when the Business Portfolio you’re trying to use is either:

  • Not verified, or
  • Has already reached the maximum number of WhatsApp accounts allowed.

Non-verified portfolios can only add up to 2 WhatsApp accounts.
Verified portfolios can add up to 20 WhatsApp accounts.

How to fix it:
We strongly recommend that you verify your Meta Business Portfolio. If verification isn’t an option and you don’t want to remove existing accounts, you can try creating a new Meta Business Portfolio. However, if the new portfolio still doesn’t allow you to add the account, business verification will be required to proceed.

“The Account is already connected to Cloud API”

This happens if your number is already connected to the WhatsApp Cloud API—either because you used it with another platform, or you previously connected it to BotCommerce via the Embedded Signup Flow. You need to  convert it to a Business account (to be used both on your phone and in BotCommerce), or move it to another portfolio.

How to fix it:
Go to the Meta Business Manager where your WhatsApp account is connected. In the left sidebar, go to Partners. Find the partner the number was connected to (e.g., Planify X – BotCommerce), then click Remove. This removes the partner connection.

Then, go to Accounts > WhatsApp Accounts and locate your number. Click Remove to delete the WhatsApp account from the portfolio. Once removed, wait 24 hours before trying to reconnect it again.

“The Account is not eligible for QR Code Connection”

This error may appear for the following reasons:

  • You’re trying to use a personal WhatsApp account, not a Business one.
  • Your WhatsApp Business account is too new.
  • Your phone number is from a country or region not supported by Meta’s QR Code connection.

Unsupported regions include:
Australia, India, Japan, Nigeria, Philippines, Russia, South Korea, South Africa, Turkey, the European Union, the European Economic Area, and the United Kingdom.

How to fix it:

If your country is unsupported, you’ll need to:

  • Use a number from a supported region, or
  • Connect via Cloud API instead.

For the other cases, follow the steps below.

Migrate the number to a WhatsApp Business account 

If your number is on a personal WhatsApp, you must migrate it to WhatsApp Business. This process is simple and safe — no information will be lost.

  1. (Optional but recommended) Back up your chats: Go to Settings > Chats > Chat Backup on your WhatsApp Messenger account.
  2. Download and install WhatsApp Business from the Google Play Store or Apple App Store.
  3. Open WhatsApp Business, accept the terms, and log in with your existing number. Your chats and media will appear just like before.

Use the Number for a Few Days

Once migrated or if you have just created the account, you’ll need to use the WhatsApp Business number regularly before it becomes eligible for QR Code connection. Keep interactions active by chatting with various customers over the next few days. After enough usage, your number should become eligible.

Final Thoughts

Connecting your WhatsApp account to BotCommerce can occasionally present challenges, but they’re usually solvable with the right steps:

  • Make sure your Business Portfolio is verified.
  • Clear old API connections if you’re switching platforms.
  • Use a proper WhatsApp Business number from a supported region.
  • If your account is too new, just give it a few days of regular activity.

Still unsure which connection method to use? Our team is here to help! Hire an expert here.

Need Help Finding A Tutorial?

Use the WebChat in the bottom-right corner to search tutorials. Be clear and specific for best results.