Migrate WhatsApp Business App Number to API: What to Prepare

Migrate WhatsApp Business App Number to API: What to Prepare

To migrate a WhatsApp Business app number to the official API, you first have to choose between two paths: switch the app off and move everything to the API, or keep the app and the API active on the same number using Meta's coexistence feature. Either way, before you touch the number you need to preserve the history, define who handles what, have the business verified and write a rollback plan. The rest is execution in the right order, with a short pilot before the whole operation moves to the new flow.

Key takeaways

• The migration changes how the number is operated, not just the technology. The API has no app screen, so your team needs a customer service tool.
• Coexistence lowers the risk for teams that cannot stop using the app, but it has feature limitations that you should check in Meta's current documentation.
• Do not treat chat history as guaranteed. Export and store what the business needs before any step.
• Team access, permissions and human handoff rules must be ready before switch day, not after.
• A written rollback plan, with the SIM card, the phone and the access codes at hand, is what makes the migration a reversible decision.

What changes when the number leaves the app and moves to the API?

In the app, an agent opens the phone or WhatsApp Web, sees the conversations, labels and quick replies, and simply answers. On the official API, the number is operated by software: messages arrive through a webhook in a system, and the team replies through a customer service platform, a CRM or a custom-built panel. This change of interface is the one that catches most companies by surprise.

The conversation rules change too. Messages the business starts outside the service window require approved templates and the contact's consent. Read WhatsApp outbound messages, templates and opt-in carefully before you plan campaigns or reminders in the new format.

Finally, responsibility changes. With the app, the account belongs to whoever holds the phone. With the API, there is a Meta business account, business assets, tokens and providers. If all of that sits with a single person, or with a vendor without a clear contract, the number becomes hostage to one login.

Full migration or coexistence: how do you decide?

Coexistence is an official Meta feature that lets you use the same number in the WhatsApp Business app and on the API at the same time. It exists precisely for companies that already serve customers from a phone and do not want to stop operating. The requirements, limitations and what gets synced change over time, so the rule is simple: confirm everything in the official WhatsApp Business Platform documentation before you decide.

A decision guide that works in practice:

• If your current team is small, depends heavily on the phone and wants to add automation gradually, start by evaluating coexistence.
• If the company will serve customers with several people, in queues, with routing and reports, and the app will stop making sense, a full migration tends to be cleaner.
• If you rely heavily on features that exist only in the app, list each one and check whether it is still available in the mode you chose. Do not assume.
• If the number is critical and the business cannot tolerate any downtime, prefer the path that lets you go back faster, even if the automation gains arrive more slowly.
• If the number is still a personal WhatsApp account, fix that first. Personal and business accounts follow different paths.

There is no single answer. The criterion is the cost of getting it wrong: how much the business loses if the number is offline for a few hours, and how much it loses if the team has to work without a function they used every day.

What happens to the conversation history?

This is the question that causes the most anxiety, and the honest answer is that it depends on the path you choose and on the rules in force. In a migration where the number is registered on the API and stops working in the app, do not count on the history appearing automatically in the new system. Depending on the signup flow, Meta may offer syncing of part of the history, but the scope and conditions must be checked in the documentation at the time of migration.

So treat the history as an asset the company must protect on its own:

• Define what really matters to keep: agreed prices, promised deadlines, open orders, complaints, warranty details.
• Export the relevant conversations using the app's own features and store them in a controlled location with restricted access.
• Record active contacts in your CRM with name, last interaction and status, so the team does not start from zero.
• Save your current quick replies, catalog and labels in a document, because they will need to be rebuilt in the new flow.

There is also a data protection dimension. In Brazil, the LGPD applies, and support history contains personal data, so keeping it with no purpose and no retention period is a risk. Define how long the company keeps these conversations, who can access them and how deletion requests are handled. The ANPD, Brazil's data protection authority, publishes official guidance on the subject, and it is worth aligning with whoever handles privacy in your company before exporting everything to a shared folder.

How do you prepare the support team?

Migrations fail more often because of people than because of technology. The agent who used to answer on a phone will now use a panel, and if they cannot find yesterday's conversation, they will go back to their personal phone and the company loses control.

Preparing the team means settling four things before switch day:

• Tool: choose where the team will work and test it with real sample conversations, not just test messages.
• Roles: define who sees all conversations, who sees only their own queue and who administers the account. Apply the principle of least privilege, as described in OWASP's authorization guidance.
• Service rules: opening hours, expected response time, what to do with audio, images and documents, and when to pass a conversation to someone else.
• Human handoff: if there is automation or an AI agent, write down when it stops and hands the conversation over, and how the agent sees what has already been said.

If the idea is to connect an AI agent to the number, how to integrate AI into your company's WhatsApp explains the overall design. And since a migration is a good moment to review habits, also read about how to avoid a WhatsApp ban when automating with AI, because sending without consent and abrupt volume increases are common causes of problems.

Step by step: how to migrate without stopping support

The order below works as a work plan. Each step should have an owner and a clear definition of done.

• Step one: take inventory of the number. Note who uses it, on which devices, which flows depend on it (website, ads, email signature, printed cards) and whether two-step verification is active. Locate the PIN, if there is one.
• Step two: confirm the business foundation. The Meta account, the administrators and the business verification must be in order. Meta business verification for the WhatsApp API covers this process in detail.
• Step three: choose the provider or direct integration and check what it offers for the path you chose, full migration or coexistence.
• Step four: save the history and assets as described above, and ask the responsible person to validate what was stored.
• Step five: prepare templates and outbound messages. Submit them for approval early, because approval can take time.
• Step six: configure the support tool, the roles and the webhook, and test on a staging number, not the production number.
• Step seven: make the switch during a low-traffic period, with the team present and the rollback plan printed next to them.
• Step eight: follow the first conversations one by one, comparing with what the app used to do. Record delivery failures, unanswered messages and team questions.

Illustrative scenario: a custom furniture shop

This scenario is illustrative. Imagine a small custom furniture shop where two people answer from the same number on the company phone. Customers send photos of the room, measurements and voice notes. The owner wants to add a third agent and an AI agent that does first-line triage after hours, without losing the number that is already on the business cards and the Instagram profile.

The shop decides to evaluate coexistence, because it cannot go without service on Saturday, its busiest day. Before switching, it exports the conversations with quotes in progress, records every customer with an open project in the CRM and writes three rules for the automation: collect the room details and measurements, never state a delivery date, and pass to a person whenever there is a complaint or a discount request. In the first week, the agent works only after hours, and the team reviews every conversation on Monday.

The example is only illustrative, but it shows the pattern: a risk-driven decision, saved history, short automation rules and an observation period before expanding.

How do you build the rollback plan?

The rollback plan is the part most companies skip, and it is what gives you the confidence to execute the rest. The question is: if tomorrow morning support through the API is not working, what do we do in the first few minutes?

A minimum plan includes:

• Physical access to the SIM card and the phone, so you can receive a verification code by SMS or call if the number has to be registered again.
• The two-step verification PIN stored in a safe place, with more than one authorized person able to access it.
• An objective trigger, for example: messages not delivered for a defined period, or a panel failure that prevents replying to customers.
• A person responsible for deciding on the rollback, with a named backup.
• A ready-made message for customers and for the team, explaining that support is being adjusted and which alternative channel to use.
• Confirmation, in Meta's documentation, of what happens to the history and to conversations created during the API period if the number goes back to the app.

It is also worth defining in advance what stopping for good means. If the pilot does not meet what was agreed, the company should be able to end it without embarrassment. How to measure an AI automation pilot helps you choose the decision criteria.

How this work fits the map, limit, pilot and hand over method

Mapping is the inventory of the number and the history: who uses it, for what, with which data. Limiting is deciding what the automation and each person can see and do, including what the AI never answers on its own. Piloting is migrating one real flow, with a record of decisions and an agreed metric, before moving the rest. Handing over is giving the documented operation to the team and then deciding whether to expand, adjust or stop. None of these stages depends on a promise of results: each one produces a record that supports the next decision.

Frequently asked questions

Can I migrate the number without losing old conversations? It depends on the path and on Meta's current rules, so do not treat preservation as guaranteed. Export and store what the business needs before any change, and confirm in the documentation what can be synced in your flow.

Can the team keep using the app after the migration? With the coexistence feature, using the app and the API on the same number is supported, but with feature limitations you should check in the documentation. In a full migration, the app stops being the support channel and the team works in the tool connected to the API.

Do I need to verify the business with Meta before migrating? Business verification is usually part of the path to operating on the API reliably, and leaving it for later can delay the project. Start with it, confirm the current requirements and keep more than one administrator registered on the business account.

Can I go back to the app if something goes wrong? In general it is possible to register the number in the app again, but what happens to the history and to conversations held on the API should be confirmed beforehand. That is why the rollback plan must include the SIM card, the phone, the PIN and a person responsible for the decision, all defined before switch day.

Sources

• Meta: documentação da WhatsApp Business Platform (Cloud API)
• ANPD: Autoridade Nacional de Proteção de Dados
• OWASP: guia de autorização