> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp connection troubleshooting

Use this page when connecting a WhatsApp number to Nexor does not finish cleanly. The symptoms below are grouped by connection method, plus a final section on payment and billing issues that block template sending.

Most blockers are controlled by Meta, not by Nexor. Nexor surfaces the error, but the fix usually happens in your Meta Business settings.

<Info>
  Two Meta pages are referenced throughout this guide:

  * [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) — number status, capacity, and warnings.
  * [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) — WABA status, business verification, billing, and payment prompts.
</Info>

## Before you retry anything

Whatever method you use, check these first:

* You are logged into the correct Facebook account.
* You have admin or sufficient access to the right Meta Business Portfolio.
* The selected Business Portfolio has capacity for another WhatsApp phone number.
* [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) shows no unresolved number-status or capacity issues.
* [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) shows no unresolved WABA status, business verification, billing, or payment prompts.
* Your business profile has complete information, including a public HTTPS website if Meta asks for one.

<Warning>
  Never choose **Display name only** in Meta's flow for any connection method. That option can create a generic, limited Meta-managed number instead of the number you intend to connect. These numbers are heavily limited and often stop sending very quickly, and require display-name approval before you can keep using them, which can also take significantly longer. If you already completed setup with **Display name only**, disconnect or delete that profile before restarting.
</Warning>

## Instant setup

Instant setup uses Meta embedded signup to connect a Nexor-provided WhatsApp number. It only works when you select a Nexor-provided number inside Meta, listed under **BSP provided number**.

<AccordionGroup>
  <Accordion title="The Meta popup does not open">
    <Steps>
      <Step title="Use a supported browser">
        Use Chrome or Firefox.
      </Step>

      <Step title="Disable blocking extensions">
        Disable ad blockers and privacy extensions for the setup session, and allow popups and cookies.
      </Step>

      <Step title="Log in first">
        Log into Facebook before restarting setup.
      </Step>

      <Step title="Restart">
        Restart instant setup from Nexor.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Your Business Portfolio or WABA is missing">
    This usually means the wrong Facebook account is logged in, the WABA belongs to another Business Portfolio, or your Meta user does not have enough permissions.

    <Steps>
      <Step title="Confirm the account">
        Confirm you are logged into the Facebook account that owns or manages the business.
      </Step>

      <Step title="Verify the WABA exists">
        Open Meta Business Settings and verify the WABA exists under that business.
      </Step>

      <Step title="Fix access">
        Ask a Meta business admin to grant access if you cannot see the business or WABA.
      </Step>

      <Step title="Retry">
        Retry instant setup after access is corrected.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The business profile step is stuck and Next is disabled">
    Meta could not validate your business profile data.

    <Steps>
      <Step title="Use a real website">
        Use a real public HTTPS website and confirm it loads in an incognito browser.
      </Step>

      <Step title="Match your details">
        Make sure the legal name, address, website, and phone number match the business.
      </Step>

      <Step title="Restart the popup">
        Restart the Meta popup after updating the information.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta does not show BSP-provided numbers">
    If Meta only shows **Add a new WhatsApp number** or asks you to type a phone number, do not continue in that flow.

    <Steps>
      <Step title="Cancel and restart">
        Cancel the Meta popup and restart instant setup from Nexor.
      </Step>

      <Step title="Choose the right option">
        At the phone-number step, choose **Use a new or existing WhatsApp number**.
      </Step>

      <Step title="Select a provided number">
        Select a number under **BSP provided number**.
      </Step>

      <Step title="If the section is still missing">
        Check WhatsApp Manager for account limits or restrictions.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="BSP-provided numbers appear but setup still fails">
    Visible BSP-provided numbers do not always mean the number pool is the blocker. Meta can still reject setup because of WABA, Business Portfolio, compliance, or phone-number-capacity state.

    <Steps>
      <Step title="Open phone numbers">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) for the same Business Portfolio used in setup.
      </Step>

      <Step title="Check status and warnings">
        Check number status, phone-number capacity, and any visible warnings on the selected WABA.
      </Step>

      <Step title="Resolve and retry">
        Resolve any Meta warnings, restrictions, or review requests, then retry instant setup.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta asks for SMS or voice verification">
    SMS or voice verification means Meta moved you into manual number registration, not instant setup.

    <Steps>
      <Step title="Cancel and restart">
        Cancel the Meta popup and restart instant setup from Nexor.
      </Step>

      <Step title="Select a provided number">
        At the phone-number step, select a number under **BSP provided number**. Do not type a new phone number.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The portfolio cannot add another phone number">
    Meta enforces phone-number capacity at the Business Portfolio level. New portfolios usually start with capacity for **2 registered WhatsApp business phone numbers**. Meta can later raise this to **20** after business verification or after the portfolio reaches a 2,000 messaging limit.

    When the portfolio has no capacity left, embedded signup can fail without a clear inline error. You may see only a red indicator on the phone-number step, a disabled **Add phone number**, or capacity text such as `1 of 2 added`.

    <Steps>
      <Step title="Review all numbers">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and review every number across every WABA under the selected Business Portfolio.
      </Step>

      <Step title="Remove unused numbers">
        Remove unused, pending, or stale numbers if you have Meta admin access.
      </Step>

      <Step title="Raise your limit">
        Complete Meta Business Verification if you need higher phone-number limits.
      </Step>

      <Step title="Retry">
        Retry after Meta shows capacity is available.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta shows error #2655121">
    This usually points to a Meta-side restriction on the selected WABA or Business Portfolio.

    <Steps>
      <Step title="Review alerts">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and review WABA, phone-number, or Business Portfolio alerts.
      </Step>

      <Step title="Check account-level setup">
        If Meta points to account-level setup, open [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) and check WABA status, business verification, and billing or payment prompts.
      </Step>

      <Step title="Request review">
        Use Meta's **Request Review** option if available.
      </Step>

      <Step title="Retry">
        Retry instant setup only after Meta clears the restriction.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta shows error 141000">
    Meta could not link the phone number to the selected WhatsApp account, or the number stayed pending or blocked after selection.

    <Steps>
      <Step title="Check the WABA">
        Check the selected WABA in WhatsApp Manager and resolve any verification or account warnings.
      </Step>

      <Step title="Retry">
        Retry instant setup.
      </Step>

      <Step title="Try another number">
        If the same provided number remains pending, restart and choose a different BSP-provided number.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The WABA review is pending and the number stays pending">
    Every newly created WABA goes through a Meta review before it is fully onboarded. During this period the number can stay pending even if the Business Portfolio already shows as verified.

    <Steps>
      <Step title="Confirm status">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and confirm the number status.
      </Step>

      <Step title="Complete business info">
        Make sure the Business Portfolio has complete business information, including legal name, address, business phone number, and a public HTTPS website.
      </Step>

      <Step title="Take any requested action">
        Complete any visible Meta-requested action if one appears. If no action appears, wait for Meta to finish the WABA review.
      </Step>
    </Steps>

    <Note>
      Nexor saves the WABA review status and shows it on the connected number while it is pending. When Meta sends the review update, Nexor automatically retries phone registration. You do not need to keep restarting instant setup unless support asks you to.
    </Note>
  </Accordion>

  <Accordion title="The WABA is banned or restricted (141014, 131031)">
    If Meta shows errors such as `141014`, `131031`, or language about a banned WABA, account lock, compliance review, or business review, the blocker is controlled by Meta.

    <Steps>
      <Step title="Check warnings">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and check for WABA or phone-number warnings.
      </Step>

      <Step title="Check account-level setup">
        If Meta points to account-level setup, open [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) and check WABA status, business verification, and billing or payment prompts.
      </Step>

      <Step title="Remediate">
        Complete any requested business verification, review, or remediation steps.
      </Step>

      <Step title="Retry with a clean WABA">
        Retry with a WABA that is not blocked.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## WhatsApp Business App (coexistence)

Coexistence lets you use the **WhatsApp Business App** and Nexor at the same time. It is convenient, but less stable than a dedicated Cloud API connection.

The standard flow is: in Nexor, start the WhatsApp connection (from an agent's **WhatsApp** channel or from **Integrations → WhatsApp**) → choose **WhatsApp Business App** → log in with Facebook → scan the QR code shown by Meta. If it works, the number stays active in the phone app and in Nexor.

<Note>
  Coexistence only changes the connection mode. It does not remove display-name approval, business verification, payment-method, or template restrictions. If you need maximum stability for production, use the dedicated / Cloud API path instead.
</Note>

<AccordionGroup>
  <Accordion title="The number was previously connected as Cloud API or with another provider">
    This is the most common source of failures, especially after migrations from another BSP.

    <Steps>
      <Step title="Open the old WABA">
        In Meta Business Settings, open **Accounts → WhatsApp accounts** and select the old WhatsApp account / WABA for the number.
      </Step>

      <Step title="Check what to keep">
        Check whether that WABA has other active production numbers, templates, or assets you need. If it does, preserve, migrate, or recreate anything you need before continuing.
      </Step>

      <Step title="Remove partners">
        Open **Partners** and remove every partner listed for that WhatsApp account.
      </Step>

      <Step title="Remove the WABA">
        Delete or remove the WhatsApp account from the Business Portfolio.
      </Step>

      <Step title="Clean up in Nexor">
        In Nexor, remove the number under **Integrations → WhatsApp** if it still appears there.
      </Step>

      <Step title="Reconnect">
        Start the Nexor coexistence flow again and create or select a new WABA in Meta embedded signup.
      </Step>
    </Steps>

    <Warning>
      Removing the WhatsApp account from the Business Portfolio does **not** delete the WhatsApp Business App account on the phone. It can affect other production numbers, templates, and partner access inside the same WABA, so only continue after you have checked that the old WABA is safe to remove.
    </Warning>
  </Accordion>

  <Accordion title="Your existing WABA does not appear in embedded signup">
    This usually means you selected the wrong Business Portfolio, the WABA is still controlled by another partner, or the number is still tied to an older WABA or app assignment.

    <Steps>
      <Step title="Confirm the portfolio">
        Confirm you are logged into the correct Business Portfolio in Meta.
      </Step>

      <Step title="Look elsewhere">
        Check whether the WABA appears under a different portfolio.
      </Step>

      <Step title="Check partners">
        Check whether an old partner still appears in the **Partners** tab.
      </Step>

      <Step title="Retry">
        Retry after the cleanup steps above. If you use your own Facebook developer app, consider **Manual setup** instead of embedded signup.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The QR flow does not show, or Meta pushes you to SMS or voice verification">
    During onboarding, choose the path for connecting the **WhatsApp Business App**. Choosing the wrong option can leave the number attached to the wrong app or with missing webhook subscriptions.

    <Steps>
      <Step title="Restart">
        Restart the flow from Nexor.
      </Step>

      <Step title="Choose WhatsApp Business App">
        Make sure you chose **WhatsApp Business App** and use the QR-based pairing path.
      </Step>

      <Step title="Avoid the wrong paths">
        Do not choose the wrong "existing app" path, and do not choose **Display name only**.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta says the number is not eligible or needs more app activity">
    Meta can block the phone-number step with a message that the number is not eligible to connect to the WhatsApp Business Platform, or that more activity in the WhatsApp Business App is needed to determine eligibility.

    If the number or account is new, first make sure the number is active in the **WhatsApp Business App**, then retry the Nexor coexistence flow. If the error keeps appearing, resetting the WhatsApp Business App account for that number is often the most reliable recovery:

    <Steps>
      <Step title="Delete the account">
        In the WhatsApp Business App, open **Settings → Account → Delete account** and delete the WhatsApp Business account for that phone number.
      </Step>

      <Step title="Recreate it">
        Create the account again in the WhatsApp Business App using the same phone number.
      </Step>

      <Step title="Restart in Nexor">
        Return to Nexor and restart the **WhatsApp Business App** coexistence flow.
      </Step>
    </Steps>

    <Note>
      Do not link the number manually to a Meta Business Portfolio before retrying. Create the account in the WhatsApp Business App first, then let the Nexor flow handle the Meta connection. If the error persists after recreating the account, try a different phone number, keeping the exact Meta error text and screenshots from the Meta popup on hand.
    </Note>
  </Accordion>

  <Accordion title="Error 3441041 — number not associated with the selected business">
    Meta shows this error when the phone number is not associated with the business selected in the flow. In practice this often happens when the number is still associated with a different company or portfolio, an old BSP relationship is still partially attached, or the number was cleaned up only on the app side but not on the portfolio or WABA side.

    <Steps>
      <Step title="Open the WABA">
        In Meta Business Settings, open **Accounts → WhatsApp accounts** and select the WhatsApp account / WABA currently associated with the number.
      </Step>

      <Step title="Check what to keep">
        Check whether that WABA has other active production numbers, templates, or assets you need. If it does, preserve, migrate, or recreate anything you need first.
      </Step>

      <Step title="Remove partners">
        Open **Partners** and remove every partner listed for that WhatsApp account.
      </Step>

      <Step title="Remove the WABA">
        Delete or remove the WhatsApp account from the Business Portfolio.
      </Step>

      <Step title="Clean up and reconnect">
        Remove the number under **Integrations → WhatsApp** in Nexor if it still appears, then reconnect from Nexor and create or select a new WABA in Meta embedded signup.
      </Step>
    </Steps>

    <Note>
      If the error persists after full cleanup, gather the `phone_number_id`, the `waba_id`, the exact Meta error, and screenshots of the relevant Meta pages.
    </Note>
  </Accordion>

  <Accordion title="Error 2655093 — account already shared with another partner">
    Meta shows this error when the business is already sharing that WhatsApp Business Account with another partner, and switching partners is not supported in this flow. Typically Meta says the number is still shared with a partner or must be disconnected first, even when you believe the previous provider is already disconnected.

    <Steps>
      <Step title="Re-check the app">
        Re-check the WhatsApp Business App for business-platform connections.
      </Step>

      <Step title="Re-check partners">
        Re-check the **Partners** tab in WhatsApp Manager.
      </Step>

      <Step title="Re-check the portfolio">
        Re-check whether the WhatsApp account still lives under an old portfolio.
      </Step>

      <Step title="When cleanup isn't enough">
        If all visible associations are gone and the error remains, Meta may still treat the number as linked to a previous partner even after visible cleanup.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

<Info>
  Known coexistence behaviors to expect: occasional disconnects, some WhatsApp Web sync issues, some contact-name sync issues, and some first inbound messages may not reach Nexor immediately. If your use case needs stable automation, templates, webhooks, and production reliability, use the dedicated / Cloud API path instead.
</Info>

## Bring your own number

Bring your own number uses Meta embedded signup to connect a phone number you control as a dedicated Cloud API number. The number should not stay active in the WhatsApp Business App after setup.

In addition to the [shared pre-flight checks](#before-you-retry-anything), confirm that:

* The number can receive SMS or voice calls during setup.
* The number is not already connected to another Nexor project.
* The number is not still attached to another WABA, previous provider, or WhatsApp Business App account.
* Two-step verification is disabled in the source WABA if Meta requires it.

<AccordionGroup>
  <Accordion title="Your Business Portfolio, WABA, or profile is missing">
    This usually means the wrong Facebook account is logged in, the WABA belongs to another Business Portfolio, or your Meta user does not have enough permissions.

    <Steps>
      <Step title="Confirm the account">
        Confirm you are logged into the Facebook account that owns or manages the business.
      </Step>

      <Step title="Verify the WABA">
        Open Meta Business Settings and verify the WABA exists under that business.
      </Step>

      <Step title="Fix access">
        Ask a Meta business admin to grant access if you cannot see the business or WABA.
      </Step>

      <Step title="Create a new profile">
        If the portfolio and WABA are correct but your number is missing, choose **Create a new WhatsApp Business profile**.
      </Step>

      <Step title="Retry">
        Retry after access and asset selection are corrected.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta only shows unrelated WhatsApp Business profiles">
    Meta may show existing profiles under the selected business account. That list is scoped to the selected Meta business context; it is not a list of every number you control.

    <Steps>
      <Step title="Do not pick an unrelated profile">
        Choose **Create a new WhatsApp Business profile** if Meta offers it.
      </Step>

      <Step title="Verify your number">
        Continue to phone-number entry and verify the intended number.
      </Step>

      <Step title="Fix the portfolio if needed">
        If the correct Business Portfolio is missing, restart while logged into a Facebook account with full admin access.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The portfolio cannot add another phone number">
    Meta enforces phone-number capacity at the Business Portfolio level. New portfolios usually start with capacity for **2 registered WhatsApp business phone numbers**, which Meta can later raise to **20** after business verification or after the portfolio reaches a 2,000 messaging limit.

    When the portfolio has no capacity left, embedded signup can fail without a clear inline error. You may see only a red indicator on the phone-number step, a disabled **Add phone number**, or capacity text such as `1 of 2 added`.

    <Steps>
      <Step title="Review all numbers">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and review every number across every WABA under the selected Business Portfolio.
      </Step>

      <Step title="Remove unused numbers">
        Remove unused, pending, or stale numbers if you have Meta admin access.
      </Step>

      <Step title="Raise your limit">
        Complete Meta Business Verification if you need higher phone-number limits.
      </Step>

      <Step title="Retry">
        Retry after Meta shows capacity is available.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Nexor says the number already exists">
    If Nexor says `A WhatsApp config with the same display phone number already exists`, the number is already connected to another Nexor account or project.

    <Steps>
      <Step title="Disconnect first">
        Disconnect the number from the Nexor account where it is currently connected.
      </Step>

      <Step title="Both accounts are yours">
        If you own both accounts, be ready to prove that you control the number and both accounts.
      </Step>

      <Step title="Stop retrying">
        Do not keep retrying the same setup. The number cannot be connected twice.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta says the number is already linked elsewhere">
    Meta can block setup when the number is still attached to another WABA, previous provider, WhatsApp Business App registration, or stale ownership state.

    <Steps>
      <Step title="Remove from old WABAs">
        Remove the number from old WABAs in WhatsApp Manager where you have admin access.
      </Step>

      <Step title="Disconnect old links">
        Disconnect old Business Platform or partner links.
      </Step>

      <Step title="Remove from the app">
        Remove the number from the WhatsApp Business App path if it was used there.
      </Step>

      <Step title="Disable two-step verification">
        Disable two-step verification in the source WABA if Meta requires it.
      </Step>

      <Step title="Wait and retry">
        Wait a few minutes for Meta cleanup to settle, then retry through one path only.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="SMS or voice verification fails">
    SMS or voice verification is expected for Bring your own number. It proves you control the phone line.

    <Steps>
      <Step title="Confirm the number">
        Confirm the phone number and country code.
      </Step>

      <Step title="Use voice if needed">
        Use the voice call option if the number is a landline or cannot receive SMS.
      </Step>

      <Step title="Stop retrying">
        Stop retrying if the resend timer keeps resetting or Meta keeps rejecting the code.
      </Step>

      <Step title="Wait out a reset loop">
        For persistent pending or reset loops, wait 72 hours with no verification, registration, deregistration, SMS, or voice attempts.
      </Step>

      <Step title="Clean up before retrying">
        Before retrying, remove stale WABA, WhatsApp Business App, and previous-provider attachments where applicable.
      </Step>

      <Step title="One clean retry">
        After the quiet window, do one clean retry through Nexor.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="The business profile step is stuck and Next is disabled">
    Meta could not validate your business profile data.

    <Steps>
      <Step title="Use a real website">
        Use a real public HTTPS website and confirm it loads in an incognito browser.
      </Step>

      <Step title="Match your details">
        Make sure the legal name, address, website, and phone number match the business.
      </Step>

      <Step title="Restart the popup">
        Restart the Meta popup after updating the information.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="WABA review blocks registration and the number stays pending">
    Every newly created WABA goes through a Meta review before it is fully onboarded. During this period SMS or voice verification may succeed, but the number can still stay pending while Meta finishes the review.

    <Steps>
      <Step title="Confirm status">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and confirm the number status.
      </Step>

      <Step title="Complete business info">
        Make sure the Business Portfolio has complete business information, including legal name, address, business phone number, and a public HTTPS website.
      </Step>

      <Step title="Take any requested action">
        Complete any visible Meta-requested action if one appears. If no action appears, wait for Meta to finish the review.
      </Step>
    </Steps>

    <Note>
      Nexor saves the WABA review status and shows it on the connected number while it is pending. When Meta sends the review update, Nexor automatically retries phone registration. You do not need to keep restarting Bring your own number unless support asks you to.
    </Note>
  </Accordion>

  <Accordion title="WABA, business, or payment restrictions block setup">
    Meta can block setup or later sending even after the number appears connected. Common causes: the WABA is banned, restricted, or under compliance review; the Business Portfolio is under compliance review; payment eligibility or billing information is incomplete; the display name is still pending or rejected; or country restrictions apply.

    <Steps>
      <Step title="Check warnings">
        Open [WhatsApp phone numbers](https://business.facebook.com/latest/whatsapp_manager/phone_numbers) and check for WABA or phone-number warnings.
      </Step>

      <Step title="Check account-level setup">
        If Meta points to account-level setup, open [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) and check WABA status, business verification, and billing or payment prompts.
      </Step>

      <Step title="Complete what Meta asks">
        Complete any requested business verification, review, or billing information.
      </Step>

      <Step title="Retry and test">
        Retry only after Meta clears the restriction, then send a production test message before treating the number as fully ready.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Meta succeeds but Nexor stays pending">
    Meta can show success while Nexor still cannot finish creating the connected number.

    <Steps>
      <Step title="Confirm Meta success">
        Confirm Meta showed success.
      </Step>

      <Step title="Check Nexor">
        Confirm whether Nexor still shows setup as pending or failed.
      </Step>

      <Step title="Retry cleanly">
        Retry once in a clean browser session if no number was created.
      </Step>

      <Step title="If the error persists">
        If Meta reports success but Nexor still cannot create the number, wait a few minutes and retry.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Payment method

WhatsApp templates can fail even when the template itself is approved. If Meta cannot bill the WhatsApp Business Account (WABA), it blocks outbound template messages until payment and business setup are complete. Nexor surfaces the error, but the fix happens in Meta Business settings.

### Common error messages

You may see one of these in Nexor health checks, broadcasts, workflows, or API responses:

| Message                                                                                     |
| ------------------------------------------------------------------------------------------- |
| `There is an issue with the payment method`                                                 |
| `Meta blocked this template because your WhatsApp Business account is not payment eligible` |
| `Payment method required`                                                                   |
| `WhatsApp Business Account is not eligible to send template messages`                       |

### Why this happens

Template messages are billed by Meta. Sends are usually rejected because of one of these:

* No active payment method on the WABA account.
* A payment method that failed verification.
* Missing business details in Billing Hub.
* Missing tax information when Meta requires it.
* WhatsApp account status still in review or restricted.

### How to fix

<Steps>
  <Step title="Add or confirm a payment method">
    Open [Billing Hub account details](https://business.facebook.com/latest/billing_hub/accounts/details), select the account connected to Nexor, and add or confirm an active payment method. Resolve any failed-payment, verification, or billing prompts shown by Meta.
  </Step>

  <Step title="Complete business information">
    Open Business info in Meta Business settings and complete the legal business name, address, phone number, website, currency, and any required tax information. Save changes and return to Billing Hub to confirm there are no remaining prompts.
  </Step>

  <Step title="Confirm account status is approved">
    Open [WhatsApp account settings](https://business.facebook.com/latest/settings/whatsapp_account) and confirm the WABA status is **Approved**. It should not be in review, restricted, disabled, or waiting on a Meta-requested action.
  </Step>

  <Step title="Wait and retry">
    Wait 5 to 10 minutes, then retry sending the same template.
  </Step>
</Steps>

## Still stuck?

If you have worked through the steps above and the connection still fails, gather the following before you retry or escalate:

* Your Nexor project URL.
* The phone number you are trying to connect.
* The Business Portfolio and WABA you selected.
* The exact Meta error text (and `phone_number_id` / `waba_id` if you have them).
* Screenshots from the Meta popup.
* Screenshots from WhatsApp account settings or WhatsApp phone numbers if they show warnings.

<Note>
  This guide is adapted from the [Kapso documentation](https://docs.kapso.ai/docs/how-to/whatsapp). Nexor uses Kapso as its WhatsApp infrastructure provider — credit and thanks to the Kapso team.
</Note>