Skip to main content

​
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 — and sends failing with 24h-window codes after migration are in WhatsApp 24h freeform window. The full migration flow itself, with its pre-migration checklist, is 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 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 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:
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 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” — work that page first. If the send then fails on the window, the error codes are in WhatsApp 24h freeform 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.

​
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. 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; 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.

​
Escalation payload

Worked the page and still stuck? Email 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