> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting: WhatsApp migration stuck — verification, eligibility, template sync, webhooks > Unstick a WABA migration to Orbit — map the stuck stage, recheck a rejected or pending business verification, resolve 'number not migratable', fix template-sync divergence, close webhook gaps, and plan a rollback if you have to. # Troubleshooting: WhatsApp migration stuck — verification, eligibility, template sync, webhooks A WABA migration stalls in one of six ways: business verification blocks the account, Meta calls the number not migratable, the template sync returns fewer templates than the old BSP had, inbound traffic arrives at Meta but never reaches your systems, the migration needs unwinding, or the account is stuck hard enough to escalate. This page covers the migration-specific failures only. Template review (pending, rejected, reclassified) works the same on a migrated WABA as on a fresh one — that is [Troubleshoot a WhatsApp template](/troubleshooting/whatsapp-template) — and sends failing with 24h-window codes after migration are in [WhatsApp 24h freeform window](/guides/whatsapp/24h-window). The full migration flow itself, with its pre-migration checklist, is [WABA migration](/guides/whatsapp/waba-migration) — treat this page as the fault-finding companion to that guide. Business verification, migration eligibility, and template approval are Meta's calls, not Orbit's — Orbit runs Embedded Sign-up, syncs what Meta returns, and enforces the result. The re-checks below target the information you control in your Meta Business Manager; when Meta itself is the blocker, the escalation section says what to send. ## Migration stage map The [WABA migration guide](/guides/whatsapp/waba-migration) moves through five stages. Almost every stall lands on one of them — identify the stage first, because the fix and the escalation payload differ per stage. | Stage | Where it freezes | Symptom | | ------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **1 — Release from source BSP** | The source BSP's console or their compliance queue | Meta Business Manager still shows the old BSP as Solution Partner, days after you requested the release | | **2 — Add Orbit as partner** | The partner assignment in Meta Business Manager | Orbit is missing from the WABA's Partners tab, or the assignment email never arrived | | **3 — Embedded Sign-up (select existing)** | The Meta OAuth dialog | The migrated WABA does not appear in the "Select existing" list, or the popup finished but the dashboard stays disconnected | | **4 — Template sync** | The `templates/sync` call or Meta's template API | The template list in Orbit is empty or shorter than the old BSP's list | | **5 — Webhooks + first send** | Meta's webhook delivery or your own endpoints | Inbound messages are visible in WhatsApp but `message.received` never fires, or `whatsapp.template.*` verdicts never arrive | Stage 5 failures are the quietest: outbound keeps working because sending only needs the Stage 3 connection, while inbound delivery depends on a separate webhook wiring that a migration can leave pointed at the old BSP. ## Business verification pending or rejected Meta does not require approved business verification for the small (250-recipient) tier, but most WABAs you migrate are past that tier, and migration re-checks the business behind the account. Watch verification state in **Meta Business Settings → Business Info** during the window: a **pending** verification holds every tier above 250 in place, and a **rejected** one blocks template submissions that share the review quota. Recheck, in the order rejections actually come back: 1. **Legal name exact match.** The legal name in Business Info must match the submitted document character-for-character — punctuation and suffixes (`GmbH`, `Ltd.`, `Inc.`) included. A trading name where the document says the legal name is the most common rejection. 2. **Document type per country.** Meta accepts a fixed list of document types per country; a business registration certificate that works in one country is not accepted from another. Resubmit with a document type from Meta's own list for your country, not a translation of one. 3. **Website and traceability.** The business website on the account must load, name the same business, and show the address or phone the documents carry. A parked domain or a redirect to a different brand fails the review. 4. **Address consistency.** The address in Business Info, the address on the document, and the address on the website should agree. Fix the weakest of the three rather than disputing the review. 5. **Verification stuck pending with no decision.** A pending state older than \~2 weeks usually means Meta's review found nothing to decide on — resubmitting with a cleaner document set restarts the clock faster than waiting. Verification is your business's submission to Meta, so this is entirely under your control — nothing on Orbit's side gates or accelerates it. When it is rejected, fix the named item and resubmit in Business Settings; when it is pending past two weeks, escalate with the payload below. ## "Number is not migratable" — eligibility Meta checks the phone number before it allows the move, and the eligibility failure names are vague. The checks that actually gate the migration: * **The number must still be registered and active on the source WABA.** A number the source BSP already released, or one in a half-deleted state, returns not-migratable until the source side is clean. Confirm the number is still listed under the source WABA's phone numbers before retrying. * **Two-factor authentication must be enabled on the number.** Meta requires a verification PIN on a migrated number. Set (or reset) the PIN on the source side first — a number without two-factor fails eligibility with no further detail. * **The display name review must be finished.** A display name still pending Meta's review, or a rejected one, blocks the migration. Wait for the review or resubmit the display name on the source WABA, then retry. * **The business behind the number must match the destination.** The WABA you select in Stage 3 must belong to the same business the number was registered to — migrating a number into a different business's WABA is refused. If your goal is a business change, verify the destination business first, then migrate. * **Charges and disputes settle first.** An unpaid invoice or contract dispute at the source BSP blocks their release (Stage 1); Meta cannot be appealed over a BSP's finance hold. Run the checks top-down and retry the Embedded Sign-up "select existing" step after each fix — the eligibility verdict is re-evaluated on every attempt, not cached. ## Template sync divergence after migration Stage 4 pulls the WABA's templates into Orbit so the template picker and the send paths see them. Two divergence classes appear after migration: **Sync returned fewer templates than the old BSP showed.** Meta's template endpoint rate-limits the sync, so a large catalog (1,000+ templates) completes over several minutes; the partial result looks final. Re-run the sync — it is idempotent and only fills the gap: ```bash theme={null} curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/templates/sync \ -H "X-API-Key: dv_live_sk_..." ``` Only templates that exist on Meta's side can sync: a template that never finished approval on the old BSP does not exist at Meta, and a template the old BSP fronted with its own drafts UI may never have been submitted. Export the approved list from the source BSP **before** the migration (the pre-migration checklist in [WABA migration](/guides/whatsapp/waba-migration) covers this) so a post-migration gap is provable rather than guessed. **The template is approved at Meta but sends fail as missing.** If the sync ran, the divergence is almost always a `(name, language)` mismatch — the send references a template pair that is not what Meta approved (the classic case is sending with `en` where Meta approved `en_US`). If instead the template exists locally but the send resolves the wrong variant, that overlaps with [Troubleshoot "template variant missing"](/troubleshooting/template-variant-missing) — work that page first. If the send then fails on the window, the error codes are in [WhatsApp 24h freeform window](/guides/whatsapp/24h-window). Resubmit a migrated template only when Meta's own record is genuinely missing or rejected — read the verdict the same way as a fresh template in [Troubleshoot a WhatsApp template](/troubleshooting/whatsapp-template). ## Webhook gaps after migration This is the failure the guide warns about and the one nobody sees coming: outbound works, templates synced, and inbound replies disappear. Stage 5 has two independent halves, and a migration can break either. **Half one — Meta delivering to Orbit.** Embedded Sign-up wires Orbit's callback URL on the WABA automatically. If anyone edited the WABA's **Configuration → Webhooks** panel by hand during the migration (some runbooks from old BSPs tell you to), the URL must be the full `https://api.orbit.devotel.io/api/v1/whatsapp/webhook` — a bare `/whatsapp/webhook` without the `/api/v1` prefix returns 404, and Meta silently stops delivering inbound messages. To catch it: send yourself a WhatsApp message and watch the inbox; nothing arriving means Meta is not delivering to the callback, and the URL is the first thing to diff against the Stage 5 section of [WABA migration](/guides/whatsapp/waba-migration). **Half two — Orbit delivering to your systems.** The old BSP's webhook endpoints, subscriptions, and secrets do not carry over — recreate them on Orbit: 1. **Settings → Webhooks → New Endpoint**, and subscribe to at least `message.received` plus the delivery-lifecycle events (`message.sent`, `message.delivered`, `message.read`, `message.failed`). Without `message.received` your automation goes blind to inbound while the Orbit inbox still fills — the signature "inbox works, my backend doesn't" means exactly this gap. 2. Subscribe to the template events — `whatsapp.template.approved`, `whatsapp.template.rejected`, `whatsapp.template.quality_update` — if you drive template review from your own systems. After migration these events are the only automated signal that a re-submitted template moved; the dashboard bell is the manual one. 3. Sign with the secret Orbit generates for the new endpoint — shown under **Settings → Webhooks** — not the old BSP's secret. Signature verification mechanics are in [Webhook security](/webhooks/security); if deliveries arrive but fail signature checks, the secret is the first suspect. ## Rollback considerations Rollback is a real option only early. Before Stage 3 completes, the WABA has not been claimed by Orbit — re-assign the source BSP as the active partner in Meta Business Manager and the migration is undone. After Stage 3, rolling back means a second migration: release from Orbit back to the old BSP, which the old BSP may treat as a re-onboarding (fees apply on several of them). Plan the outage window in the guide's checklist assumes you migrate forward; a rollback doubles it. Two side effects to price in before deciding: * Webhook endpoints and subscriptions on the old BSP do not come back with the rollback — those lived on their system. Whoever rolls back recreates their half-two wiring on the other side. * Template sync on Orbit is idempotent and harmless under a rollback; nothing you synced here changes Meta's records. The full rollback path and the escalation route into Meta's BSP operations are in the Rollback section of [WABA migration](/guides/whatsapp/waba-migration). ## Escalation payload Worked the page and still stuck? Email [whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io) with these four items so the case routes straight to the right lane (Meta escalation vs. connection repair) without a back-and-forth: 1. Your **WABA id** — the 15-digit id from Meta Business Manager → WhatsApp Accounts (also `waba_id` on any Orbit template or phone-number record). 2. The **migration stage** you are stuck on — release, partner assignment, Embedded Sign-up, template sync, or webhooks (the stage map above). 3. The **exact error text or code**, verbatim — Meta's eligibility message ("number is not migratable"), the verification rejection text from Business Info, or the API error code from the failing sync or send, plus the timestamp of one attempt. 4. The **source BSP name** and whether their release (Stage 1) is confirmed — this decides whether the case goes to Meta's BSP operations or stays a configuration fix. ## See also * [WABA migration](/guides/whatsapp/waba-migration) — the full migration flow, pre-migration checklist, and outage planning this page troubleshoots. * [Troubleshoot WhatsApp connection, re-authentication, tier limits, and quality pauses](/troubleshooting/whatsapp-connection) — token, tier, and quality failures that look identical on migrated and fresh WABAs. * [Troubleshoot a WhatsApp template](/troubleshooting/whatsapp-template) — pending, rejected, paused, and reclassified templates. * [Troubleshoot "template variant missing"](/troubleshooting/template-variant-missing) — when a synced template still does not resolve on send. * [WhatsApp 24h freeform window](/guides/whatsapp/24h-window) — the window error codes a post-migration first send can hit. * [Webhook security](/webhooks/security) — endpoint-secret signature verification for the endpoints you recreate after migration. * [Webhook events](/reference/webhook-events) — payload shapes for `message.received`, the delivery-lifecycle events, and `whatsapp.template.*`.