WhatsApp Cloud API Migration: The 2026 On-Premises Playbook

Somewhere in most on-premises WhatsApp stacks there is a service nobody wants to restart. It was set up in 2021 or 2022, by an engineer who has since left or by a BSP whose contract renews itself quietly every year, and it works — until the week it does not. That is usually when someone asks the question that brings teams to us: when exactly is Meta switching this off, and how painful is the move?

The honest answer to the first half is that Meta has not published a final hard cutoff at the time of writing. The direction of travel is unambiguous — Meta maintains an official On-Premises to Cloud API migration guide, and publishes no guide pointing the other way — but if you want a date to put in a planning document, there isn't one. That is not a reason to wait. It is a reason to migrate on your calendar rather than on Meta's.

The second half is more answerable, and better news than most teams expect. A WhatsApp Cloud API migration preserves nearly everything commercially valuable you have accumulated on the number. What it changes is code, and the changes are narrow enough to enumerate — which is what the rest of this guide does.

Key points

• A WhatsApp Cloud API migration preserves your display name, your WhatsApp Business Account, your approved templates, your quality rating, your Official Business Account status and your messaging limits, per Meta's official migration documentation.
• Migration changes media IDs, error codes, webhook payload shapes and some validation behaviours, so the work is concentrated in your integration code rather than in your Meta assets.
• Meta has not published a final On-Premises API shutdown date at the time of writing, but it publishes a one-directional migration guide and On-Premises is being phased out in favour of Cloud API.
• Messaging limits are now set at the business portfolio level and shared across every phone number in that portfolio, which changes how you plan a phased cutover across multiple numbers.
• Newer platform capabilities including WhatsApp Business Calling are documented as Cloud API features, so staying on-premises increasingly means declining new capability rather than merely deferring a migration.
• Switching your Business Solution Provider and switching your hosting model are two different projects, and doing both in the same week is the most common way teams turn a two-week migration into a two-month one.

Cloud API vs on-premise WhatsApp: the two hosting models

The WhatsApp Cloud API is the version of the WhatsApp Business Platform that Meta hosts and operates on its own infrastructure, which you reach over HTTPS with no servers of your own to run. The On-Premises API is the version of the same platform that you, or your Business Solution Provider, install and operate on infrastructure you control, which means you also own its patching, scaling, storage and uptime.

Everything above the API — your number, your WhatsApp Business Account, your templates, your quality rating — is Meta-side in both models. The difference is who runs the machine that sends the message. That framing matters, because it explains why migration is far less destructive than teams fear: you are not rebuilding your WhatsApp presence, you are changing the door your traffic goes through.

Who is still on-premises, and why

Three reasons account for most of the teams still self-hosting, and only one of them is technical.

The first is a data-residency belief. Someone in a compliance or security review decided that messages must transit infrastructure the company controls, and on-premises hosting was the answer. It is worth revisiting that assumption carefully rather than treating it as settled, because it usually rests on an understanding of what the On-Premises client actually stores that was formed years ago.

The second is a legacy BSP contract. The provider onboarded you onto their on-premises deployment, that is how their platform was built, and migration is a conversation neither side has started. Teams in this position often discover the hosting question and the provider question are tangled together — which is exactly why the guide to choosing an Indian WhatsApp Business API provider is worth reading before you scope the work.

The third is sunk integration cost. There is a media pipeline, a retry queue, an error-mapping table and a monitoring dashboard, all written against the On-Premises API, and nobody wants to touch four working systems for an outcome that looks like parity. That is a real objection. The counter is that those four systems get smaller after migration, not larger.

Is the On-Premises API being deprecated?

Meta publishes an official On-Premises to Cloud API migration guide, last updated 26 October 2025. The On-Premises API remains operable, and it is being phased out in favour of Cloud API. Meta has not published a final hard cutoff date at the time of writing, and you should not plan around a date you saw on a vendor blog — including a date you might see attributed to us.

So treat WhatsApp on-premises API deprecation as a direction rather than a deadline, and read the direction from three signals instead of a rumour.

The first signal is the asymmetry of the documentation. There is a migration guide from on-premises to cloud and none in reverse. Platforms do not write one-way migration guides for architectures they intend to keep investing in equally.

The second signal is where new capability lands. WhatsApp Business Calling — VoIP calling between business and user, with video and screen sharing on the same business number — is documented as a Cloud API capability, and business-initiated calling is available in India. Its capacity ceiling moved from 10 business-initiated calls a day in October 2025 to 100 a day by December 2025, and G.711 codec support arrived in March 2026. That is an actively developed surface, and it is not an on-premises one.

The third signal is the 2026 pricing and product calendar. The Meta Business Agent Platform launched on 1 July 2026, per-token billing for Business Agent messages began on 1 August 2026, and from 1 October 2026 Meta resumes charging for service messages and for utility messages sent inside an open 24-hour customer service window — both free today, per Meta's pricing documentation for non-template messages. None of that is hosting-specific, but all of it means your WhatsApp integration will need real work in the next two quarters regardless. Doing that work twice, once on a platform you plan to leave, is the expensive option. The 2026 WhatsApp pricing guide covers the cost side in full.

What a WhatsApp Cloud API migration preserves, and what changes

This is the table to take into your planning meeting. The left column is why migration is less frightening than it sounds. The right column is your entire engineering scope.

Read the left column literally and gratefully. Your quality rating carries over, which matters because quality rating gates both your messaging limit progression and your throughput eligibility — a number that took eight months to reach a green rating does not restart at UNKNOWN. Your templates carry over, which matters because template review takes up to 24 hours per template and a portfolio of 300 templates would otherwise be a month of queueing. Your Official Business Account status carries over, which matters because non-OBA numbers do not appear in WhatsApp's in-app search at all, and reapplying after a rejection means a 30-day wait — the green tick verification guide explains how hard that badge is to get back.

Your messaging limits carry over too, and there is a subtlety worth stating. A messaging limit is the maximum number of unique users a business can message outside an open customer service window in a rolling 24-hour period, and limits are now set at the business portfolio level and shared across every phone number in that portfolio rather than per number. So a phased migration that moves one number at a time does not give each number its own fresh allowance — the pool is shared, and your planning has to reflect that. The messaging limits and tiers guide covers the full ladder from 250 through to unlimited.

The four code-level gotchas, and how they show up in production

The four items in the right column above are not equally dangerous. Ranked by how quietly they fail:

Media is where most teams underestimate the work, because media IDs are not just an integration detail — they are often a foreign key inside your own database. If your support tool stores a WhatsApp media ID and fetches the file on demand when an agent opens a ticket, every historical attachment breaks the moment you move. The fix is architectural rather than clever: your system should own its own copy of anything it needs to display later.

Webhooks are where most teams underestimate the risk, because a webhook consumer that half-works does not page anyone. It returns HTTP 200, parses the envelope, finds the field it wants missing, writes a null, and your delivery reporting quietly degrades into fiction. Build the new consumer as a genuinely new consumer, run both against live traffic during the dual-run window, and compare row counts rather than eyeballing logs — the WhatsApp webhooks guide covers signature verification and retry semantics in detail.

Error codes deserve one specific note. Your error map should have a loud default branch, because the code you have never seen is the one that matters. Error 131049, for example, is what a send returns when it has been throttled by WhatsApp's per-user marketing message cap — a dynamic limit, driven by that user's recent read rate and inbox load, that is active in India. Retrying it inside 24 hours risks further failures. If your retry logic treats every unrecognised code as transient, that is the code that will teach you otherwise.

The migration runbook: nine steps and a dual-run window

A dual-run window is a period during which your old and new integrations both run against production traffic, with a controlled share routed to the new path, so that you can compare behaviour before committing. Everything below is built around one.

1. Inventory every integration surface. List every place your code touches the On-Premises API: send paths, webhook consumers, media upload and download, template management, contact or number-check calls, health monitoring. Anything not on the list will be discovered at 11pm on cutover night.
2. Freeze non-essential template work. Do not ship new templates into a migration window. Template review takes up to 24 hours and you want a stable inventory to regression-test against.
3. Build the new send path behind a feature flag. One flag, one code path, defaulting to the old integration. No dual code branching scattered across services.
4. Rebuild the error map from scratch. Enumerate the Cloud API codes you handle, classify each as retryable or terminal, and make the unrecognised-code branch log at error level and stop.
5. Stand up a second webhook consumer. Point it at a new endpoint, write to a shadow table, and change nothing about the existing consumer yet.
6. Replay real payloads in test. Take your 20 highest-volume real message payloads — including the awkward ones with long parameters, media, and interactive components — and send them through the Cloud API in a test environment. This is where validation-behaviour differences surface.
7. Open the dual-run window and ramp traffic. Move 5% of sends to the new path, hold for 48 hours, then 25%, then 100%, watching delivery rate, error distribution and quality rating at each step. Keep the shadow webhook consumer running through the whole ramp.
8. Cut over fully, and keep the rollback path warm for two weeks. Rollback means flipping the flag back, not redeploying. Write down the specific trigger conditions in advance — a delivery-rate drop beyond a defined threshold, a quality-rating move to YELLOW, or webhook event volume falling below a floor.
9. Decommission deliberately. Only after two clean weeks: turn off the old webhook consumer, archive the old media store, and close the infrastructure. Delete nothing in step 8 that you would need in step 9.

Two notes on sequencing. Schedule the ramp in step 7 away from anything commercially load-bearing — not the week of a festive campaign, not the last three days of a collections cycle. And run the ramp during Indian business hours with the team available, because a 2am cutover with nobody watching turns a five-minute rollback into a six-hour incident. If you would rather not own this choreography at all, InfiQ's onboarding as an official Meta Business Solution Provider handles number registration and the dual-run alongside your engineers, with go-live in about 2 hours once assets are in place.

Worked example: a hypothetical Mumbai NBFC scopes the migration

Take a hypothetical NBFC in Mumbai running on the On-Premises API through a legacy BSP, sending roughly 400,000 messages a month across collections reminders, statement notifications and OTPs, with three integration surfaces in play.

Effort estimate, in engineer-days:

• Send path rebuilt behind a flag: 6 days
• Second webhook consumer plus shadow table and diffing: 5 days
• Media pipeline re-architected so the platform ID is no longer a foreign key: 4 days
• Error map rebuilt and retry logic reworked: 3 days
• Regression pass across templates, Flows and the agent inbox: 4 days
• Cutover, monitoring and two-week rollback readiness: 2 days

Total: 6 + 5 + 4 + 3 + 4 + 2 = 24 engineer-days. At an illustrative blended internal cost of ₹8,000 per engineer-day, that is 24 × ₹8,000 = ₹1,92,000 of engineering effort, spread across a calendar window of roughly four weeks once the 48-hour holds in the ramp are included.

That is the number teams flinch at. The comparison that matters is not ₹1,92,000 against zero — it is ₹1,92,000 once against the recurring cost of hosting, patching, monitoring and capacity-planning an API client you no longer need, plus the capability you decline by staying. Pull your own infrastructure and vendor line items before you decide.

Treat every rupee figure here as illustrative. Engineering day rates vary enormously across Indian teams, and message rates vary by market and category on Meta's published rate card, so model with your own numbers — InfiQ's WhatsApp cost calculator is a faster starting point than a spreadsheet.

Regression-testing templates, Flows and the inbox after cutover

Your templates survive migration. Whether every template still sends correctly through a new integration is a separate question, and the answer is found by testing rather than by reading documentation.

Flows deserve their own pass, because Flows carry three independent version tracks — Flow JSON, Data API and Message version — and a migration is exactly the kind of project during which someone updates a version target without telling anyone. Check each published Flow against your recorded version numbers before and after; the WhatsApp Flows implementation guide explains why version drift is the most common cause of a Flow that worked last quarter and fails today.

Watch the number's quality rating daily through the ramp, not weekly. Quality ratings run GREEN, YELLOW, RED and UNKNOWN, and Meta's own wording for YELLOW is that the number "may soon be paused or disabled". A migration should not move your rating at all. If it does, something in your new send path is reaching people it should not.

Data residency, DPDP, and what WhatsApp API hosting actually decides

This is where the conversation usually gets muddled, so here is the honest version.

WhatsApp API hosting decides where the client software that calls WhatsApp runs. It does not make your business the sole custodian of the message content, because in both models the message travels over Meta's platform to reach the user's WhatsApp client. If your compliance position assumes that on-premises hosting keeps WhatsApp message data entirely within infrastructure you control end to end, that assumption deserves a fresh review with your security and legal teams rather than an inherited answer.

India's Digital Personal Data Protection (DPDP) regime turns on clear, concise privacy notices covering purpose, data categories and retention, and on valid, informed consent. None of that is satisfied or violated by your hosting choice. It is satisfied by your consent capture, your purpose limitation, your retention discipline and your ability to honour a withdrawal — which live in your application layer, in both hosting models. Check MeitY's gazette notification and take your own legal advice; this is not it. The WhatsApp opt-in and DPDP guide covers the consent mechanics teams actually get asked about.

What migration does change is your audit surface, and mostly in your favour. Fewer systems holding message content means fewer systems to document, scan and defend in a security review. Teams that migrate often find the DPDP conversation gets easier, not harder, because the retention question narrows to their own database.

Switching BSP is a different exercise from switching hosting

Changing your hosting model and changing your Business Solution Provider are two projects that share a calendar slot and nothing else.

A hosting migration moves your number from the On-Premises API to the Cloud API while your Meta assets stay put. A BSP switch moves the commercial and platform relationship — billing, support, the application layer you work in day to day — and may or may not involve a hosting change at all.

Doing both simultaneously is possible and sometimes necessary, particularly when your current provider only offers on-premises deployment. But be clear-eyed about the diagnostic cost: when delivery drops during a combined cutover, you cannot tell whether the cause is your new code, the new hosting model or the new provider, and you will spend two days finding out. If you can sequence them, migrate hosting first with your existing provider, prove stability for a month, then evaluate providers with a clean baseline. If you cannot, insist on a written dual-run plan from the incoming provider before you sign, and look for pre-built CRM and e-commerce integrations so that the application-layer rebuild is configuration rather than code.

What most teams get wrong about Cloud API migration

They wait for a date. The single most common failure mode is treating the absence of a published On-Premises shutdown date as permission to defer. Meta has not published a final hard cutoff at the time of writing, and that is precisely the moment to migrate — on a quiet calendar week, with a rollback path, rather than inside an announced 90-day window competing with every other team on the platform for BSP attention.

They test with synthetic payloads. Clean test data passes. Your real traffic contains a 900-character parameter, a customer name with an emoji, a PDF that is nearly at the size limit and a template someone edited in WhatsApp Manager last March. Validation behaviour differences surface on those, not on {{1}} = "Test".

They migrate the send path and forget the read path. Sends are visible; a broken webhook consumer is not. Delivery and read events degrade silently, your reporting stays plausible, and three weeks later someone notices the numbers stopped moving. Diff the two consumers on live traffic.

They keep media IDs as foreign keys. Media IDs do not migrate, and a database column that stores a platform identifier and nothing else guarantees a historical-attachment outage. Own your own copy.

They cut over everything at once because parity looks obvious. Parity is a documentation claim; behaviour is an empirical question. A 5% / 25% / 100% ramp costs four days of patience and buys you the ability to notice a problem while it is still small.

They treat migration as an infrastructure ticket. It is a cross-functional project. The growth team needs to know not to launch a campaign that week, support needs to know why an attachment might not render, and finance needs to know the migration lands in the same quarter as the 1 October 2026 pricing change. Scope it as a project, or it will find you as an incident.

Get started with InfiQ

Most on-premises migrations stall for the same reason: nobody wants to own a cutover with no deadline attached to it. The teams that get through it cleanly do the boring version — inventory every surface, rebuild the error map, run two webhook consumers side by side, ramp 5% to 25% to 100%, and keep the flag warm for two weeks. Nothing clever, and no drama on the other side.

Ready to move off self-hosted WhatsApp infrastructure without losing your number, templates or quality rating? Start your 7-day free trial — InfiQ is an official Meta Business Solution Provider and gets you live on the official WhatsApp Business API in about 2 hours, with webhooks and developer APIs documented for your engineers and a shared team inbox your support team can run from day one. Or book a walkthrough if you want the migration mapped against your own integration surfaces first.