If you cannot connect your WhatsApp number to Chatwoot, use this guide to identify where setup stopped and what to check next. It covers Meta’s Embedded Signup flow, including connecting an existing WhatsApp Business app number through Coexistence. For the setup walkthrough, see [How to setup a WhatsApp channel (Embedded signup)](https://www.chatwoot.com/hc/user-guide/articles/1752129193-how-to-use-whatsapp-embedded-signup). If you use Twilio or configure your own Meta app and token, follow the [Twilio setup guide](https://www.chatwoot.com/hc/user-guide/articles/1742910590-how-to-set-up-a-whats_app-channel-with-twilio) or [manual setup guide](https://www.chatwoot.com/hc/user-guide/articles/1756799850-how-to-setup-a-whats_app-channel-manual-flow). ## Before you troubleshoot First, identify how your number is currently used: * **New number:** You are registering a number that is not currently connected to WhatsApp. * **WhatsApp Business app:** Choose Coexistence if you want to keep using the app on your phone alongside Chatwoot. Coexistence applies to the WhatsApp Business app, not the personal WhatsApp Messenger app. * **Another API provider:** Check which provider currently manages the number and whether you are moving an API connection or connecting an existing Business app account. These use different onboarding paths. Sign in with the Facebook account that has admin access to the correct Meta business portfolio. Keep your business information ready and, for Coexistence, update the WhatsApp Business app to the latest version. **Keep your existing connection working.** Do not delete your WhatsApp account, remove your WhatsApp Business Account, or disconnect your current provider as a general troubleshooting step. The correct recovery depends on the number’s current setup. Note the complete error message and the screen where it appears. Similar-looking errors can have different causes. Keep the code, if shown, together with the full message. ## Your phone number is not eligible or needs more activity You may see a message saying your number is not eligible to connect to the WhatsApp Business Platform and that more activity in the WhatsApp Business app is needed. Meta lists this as error **3441045**. This is a Coexistence eligibility check. Meta’s error reference asks for more Business app activity, but does not publish a minimum number of messages, a fixed waiting period, or a guaranteed approval date. ### What to do * Confirm that you entered the number currently used in the WhatsApp Business app. * Continue normal conversations with your customers in the app. Avoid generating artificial activity or repeatedly attempting signup. * Keep the app updated. Do not delete and recreate the account to try to clear eligibility. * After continuing normal Business app usage, try the Coexistence flow again. An older number can still fail the eligibility check; its age alone does not establish eligibility. Eligibility is determined by Meta. There is no documented setting in Chatwoot that overrides this check or guarantees approval. ## The number is not registered with the WhatsApp Business app Errors **2655095** or **2655048** can appear when the number entered does not meet the registration requirement for the selected Business app flow. * Check the number and country code. * Confirm that the number is active in the WhatsApp Business app, rather than WhatsApp Messenger. * If you are connecting a new number for API use only, use the standard number-registration path instead of the existing Business app path. If Meta asks you to update the app, including error **4563015**, install the latest WhatsApp Business app update and try again. ## The number is already registered or connected to another partner The next step depends on the exact message: * **“This phone number already exists in your list of phone numbers”:** Go back and select the existing number in the correct WhatsApp Business Account instead of adding it again. * **“This number is registered to an existing WhatsApp account”:** Check which connection path you selected. An active WhatsApp Business app number should use Coexistence if you want to keep using the app. * **“The business is already sharing this WhatsApp Business account with a partner” (2655093):** Meta has detected an existing partner relationship. This flow does not support switching partners directly. * **“Already registered with the product” or “disconnect your business platform” (3441049 or 2655094):** Meta is asking you to address an existing platform connection. * **“The phone number is not associated with the business you selected” (3441041):** Check that you selected the business portfolio associated with the number. For partner or platform conflicts, check WhatsApp Business app → Settings → Account → Business Platform to identify the current connection. In Meta Business Settings, select the correct portfolio and open Accounts → WhatsApp accounts to check the account and its partners. Confirm that these match the number and business you selected during signup. For errors **3441049** and **2655094**, Meta specifies a **15-minute wait after disconnection** before retrying. Apply this only when you have confirmed that disconnecting is the intended change and understand the effect on your current messaging service and recovery. Disconnection is not a general fix for onboarding errors. A previous provider’s shared credit line can also cause partner-switching errors. Check with your business administrator or previous provider whether their credit line is still associated with the account; checking the visible platform connection alone may not explain the failure. See the limitations in [Meta’s Coexistence guide](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users). ## The number is linked to a Facebook Page Error **2655082** indicates an existing Facebook Page association. Check the selected business in Meta Business Suite → Settings → Accounts → Pages and confirm which Page is involved. Meta’s resolution involves removing the Page association, or using another number. Before removing it, have the Page administrator confirm the ownership and effect on existing business tools. Do not delete the WhatsApp account to address a Page conflict. ## Meta says the account uses marketing messages Error **3441047** means the selected account is not eligible for this feature because it uses marketing messages. Meta directs you to select a different WhatsApp Business Account. More app activity or repeated retries is not a documented fix for this error; the reference does not say that simply turning off marketing messages will resolve it. ## The business portfolio or WhatsApp account is unavailable If an account is missing or cannot be selected, check that you are signed in with the correct Facebook account and have admin access to the business portfolio that owns the WhatsApp Business Account. * **“User does not have permission to create WhatsApp Business Accounts”:** Ask an existing business administrator to grant the required access or complete setup. * **You have reached an account-creation limit:** Use an appropriate existing account where possible. If Meta asks for business verification before you can create more accounts, complete that process. * **Business verification is in progress:** Check its status in Meta Business Suite → Security Center and follow Meta’s instructions. * **The business or WhatsApp account is restricted:** Open [Meta Business Support Home](https://business.facebook.com/business-support-home/), select the affected business or account, and review the restriction and any available appeal option. Errors include **2655089**, **3441040**, and **2388107**. Resolve the restriction through the review or appeal option shown by Meta. Once it is cleared, retry signup with the same business account. Do not create replacement accounts to work around a restriction. ### Your Facebook account is too new If Meta says your Facebook account is too new to create a business account, wait a few hours before retrying, or use an existing active Facebook account with the required business access. Do not repeatedly create accounts or restart signup during the wait. ### Verification was started with another partner Error **2494143** means partner-led business verification was already started or attempted with another partner. Continue verification with that partner, or apply for Meta Business Verification instead. Starting partner-led verification with multiple partners for the same business is not supported. ## The display name is rejected or still under review If Meta rejects the display name, review the [WhatsApp display-name guidelines](https://www.facebook.com/business/help/757569725593362), correct the business profile name, and try again. If the error says name verification is already in progress, wait for that review to finish before editing the name again. A generic error during business-profile creation can also relate to the profile name or details. Check the screen where it occurred and re-enter valid business details rather than assuming every generic error has the same cause. ## You have reached the phone-number limit If Meta says the business has reached its phone-number limit, ask your business administrator to review the existing numbers and current limit in WhatsApp Manager. If the intended number is already listed, select it instead of adding it again. For additional capacity, follow [Meta’s phone-number guidance](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/phone-numbers) and request an increase through Meta where available. Do not delete a working number just to make room. ## The verification code does not arrive or cannot be verified For standard phone registration, confirm that the number and country code are correct and that you can receive SMS or voice calls on that number. * Use the verification method offered by Meta that your number can receive. A landline needs voice verification. * Meta’s Embedded Signup error reference lists interactive voice response (IVR) numbers as unsupported. Use an operational, telecom-verified number that can receive the verification method offered by Meta. * Use the current code and avoid repeatedly requesting or guessing codes. **“You have guessed too many times”:** Meta recommends waiting about 12 hours before retrying. Return to the existing account and number when you resume. **“You have requested your code too many times” or “tried to register this number too many times”:** Stop retrying and follow the waiting period shown by Meta. Do not assume every verification error has the same cooldown. **“Code couldn’t be sent” (2388091) or “Code couldn’t be verified” (2388093):** Read the full message for the specific reason. Recheck the number, confirm that your chosen method can receive the code, and follow any waiting period before trying again. If you selected Coexistence, follow the connection and verification prompts shown in the WhatsApp Business app. Do not switch to manual phone registration to bypass a failed Coexistence step. ## The Coexistence connection prompt or QR code does not work Use the latest WhatsApp Business app on the phone where the number is active, and keep the phone online. Meta documents this connection flow: 1. In Embedded Signup, choose to connect your existing WhatsApp Business app account and enter its number. 2. Copy the verification code displayed in the signup window. 3. On your phone, open the message from the official Facebook Business Account and tap **Connect**, then **Connect to the Business Platform**. 4. Tap **Confirm** and choose whether to share your chat history. 5. Enter the copied verification code in the app, then complete the remaining signup steps. If the flow offers **Scan QR code instead**, use the scanner and code directed by that flow. If scanning fails, check camera permissions and use the current code. Screens may vary; follow the prompts shown for your account. If the connection message does not arrive, confirm that the entered number matches the active Business app account and that the phone has an internet connection. Keep the signup window open while completing the phone prompts. Avoid uninstalling the app or disconnecting an existing platform as a troubleshooting step. ## Meta says the feature is unavailable in your region Error **3441042** identifies a region-related restriction for the selected flow. This is different from the insufficient-activity error. Check that you entered the correct country code. If it is correct and Meta still rejects the region, this flow is not available for that number at the time of the attempt. You can continue using the existing WhatsApp Business app while checking Meta’s current availability guidance. Increasing app activity is not a documented fix for this error. ## The Meta window does not open or signup stops unexpectedly * Allow pop-ups for Chatwoot and Facebook. Check whether a browser extension is blocking the signup window. * Confirm that the Facebook account shown in the window is the one with access to your business. * Complete any security challenge or two-factor authentication request directly in Meta. * If Meta reports a temporary system error, wait a few minutes before trying again. If it reports a rate limit, follow that message instead of repeatedly restarting. If the same error continues, record whether it appears inside Meta’s window or in Chatwoot after the window closes. ## Meta signup finishes, but the Chatwoot inbox is not ready Finishing Meta’s window is one part of onboarding. Return to Chatwoot and complete any remaining setup steps, including adding agents. Then open Settings → Inboxes and check whether the WhatsApp inbox was created. If the inbox exists, open it and review any error shown. If the page appears stuck, refresh Chatwoot and check the inbox list again before restarting signup. Avoid creating duplicate inboxes or deleting an existing inbox. Once the inbox is ready, check that a new customer message arrives in Chatwoot and that you can reply. If you chose Coexistence, also confirm that the WhatsApp Business app still works. For issues after connection: * [Common WhatsApp issues and how to fix them](https://www.chatwoot.com/hc/user-guide/articles/1768986869-common-whats_app-issues-and-how-to-fix-them) covers delivery errors and display-name issues. * [Synchronize WhatsApp templates using a Business Management token](https://www.chatwoot.com/hc/user-guide/articles/1785260890-whatsapp-business-token) covers template access when messaging still works. * If Coexistence history synchronization is incomplete, keep the app open with a stable internet connection and confirm that you agreed to share history during onboarding. A larger history can take longer to synchronize. Meta requires synchronization within 24 hours of onboarding. If progress remains stuck, use the support checklist below promptly rather than disconnecting and restarting. ## Still stuck? Contact Chatwoot Support If the checks above do not resolve the issue, contact Chatwoot Support. Also ask for help before removing a live partner connection if you cannot confirm the effect on messaging, downtime, and recovery. Connection failures after Meta signup may require investigation on Chatwoot’s side. For account restrictions or verification reviews, first follow the instructions in Meta Business Support Home. Chatwoot cannot override Meta’s decisions. To help us investigate, include: * The complete error message and code, if shown, plus a screenshot. * The failed step and whether the error appeared in Meta or Chatwoot. * Your Chatwoot account or inbox link, if one exists. * The business phone number with country code and the time of the attempt, including time zone. * Whether the number is new, used in the WhatsApp Business app, or connected to another API provider. * For Coexistence: the app version, approximate length of use, and whether messaging still works on the phone. * The Meta business portfolio ID, WhatsApp Business Account ID, and Phone Number ID, if available. These are different identifiers; label each one. Never share your password, access token, verification code, or two-step verification PIN. Hide these details in screenshots. ## Official Meta references * [Embedded Signup errors](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/errors/) * [Onboarding WhatsApp Business app users (Coexistence)](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users)