Planning a move with the Migration readiness assistant
Who this guide is for: the customer ADMINISTRATOR and their team. Employees with viewer seats cannot open this area (see Roles and refusals).
Use the ConvoTide Migration assistant to prepare source files, review and import contacts, create local text-template drafts and check team readiness in your business. You can do this preparation before any real switch is attempted.
Before cutover. Use the assistant to prepare the destination. Moving your number, connecting a provider and sending a live test require a separate, authorized cutover.
The screenshots in this guide are simulated test data, not live delivery. They were captured in an isolated test environment with synthetic businesses and synthetic team members. Nothing illustrated here was a live customer action.
Before you start
- You need an administrator seat. The assistant is part of the admin-facing migration area. A viewer seat cannot open it (see Roles and refusals). If your seat lacks access, ask your business administrator.
- Sign in with your own account and verification method when prompted.
- Select the correct business. Every checklist, fact and confirmation is kept separately per business. Check which business is active before you rely on any result (see Switching businesses keeps answers separate).
- Device. The assistant works on desktop and on a phone-width screen; the accepted evidence covers 1440 px desktop and 390 px phone widths with no sideways scrolling.
- Language. The whole assistant is available in five languages — English, Hindi, Punjabi, Marathi and Gujarati. Switch with the language selector; headings and buttons change with it.
- Template wording. If you want to preserve message-template text, have it ready to paste into the definitions box (see Import text-template drafts).
Open the Migration assistant
- Sign in to the workspace, select your business, then open the Migration assistant.
- Use the task links at the top: 1. Keep exports, 2. Contacts, 3. Templates and 4. Check and cutover. The Team move guide below them links to the places where you can review seats, bots, routing and templates.
- Each readiness step in the checklist shows its state: unverified (not checked yet), pending-manual (waiting for you to confirm), server-complete (checked against the server), blocked (a check failed or does not apply yet) or manual-complete (you confirmed it yourself).

The assistant after a destination check, with the team facts it read from the server. Full-size image.
Prepare your source exports
- Open 1. Keep exports. Enter your current provider if helpful, then choose how you will obtain the source files: use a provider export, use originals you already have, or request help when an export is unavailable.
- If you need help, choose Download provider export request. Review the text and send it yourself through your provider's authorized support channel. The download sends nothing. Ask for contacts and suppression records, template definitions and approval details, and any available history and attachments. If a file is unavailable, record it as unavailable and continue preparing the destination. An unavailable file is not an empty export.
- Keep the originals unchanged. Work on copies and retain source record IDs, timestamps and time zones. Keep any permitted message history and attachments in a separate restricted source archive. Record which files were available, and reconcile missing attachments separately. The assistant has no chat archive upload and cannot restore earlier conversations or messaging windows.
Preview and reconcile contacts
- Open 2. Contacts. Choose Download blank CSV template if you need a starting file, or choose a CSV or XLSX copy of the source export. Keep international phone numbers as text.
- Choose Read columns and preview. If the source uses different column
names, map the phone column once and map the other supported fields. Keep
verified withdrawals in
whatsapp_opted_out(trueor1) and their source reference inwhatsapp_opt_out_reference. A blank or false withdrawal flag does not grant permission or clear a withdrawal. Choose Preview this mapping after a mapping change. - Review the source rows, duplicates, invalid entries and withdrawals before confirming the import. Previewing does not add contacts. Before committing a production import, agree on a backup and recovery procedure and start with a small authorized batch.
- After importing, check that imported, duplicate and rejected rows add up to the total. Review the recorded withdrawals separately and download the reconciliation. If the response is interrupted, check saved imports before retrying. Discarding the selected file does not undo a committed import.
See the contact import guide for receipt details.
Check destination (server-verified facts)
- Choose Check destination to read the saved account, sender, template and webhook records and see the ordered cutover checklist.
- Under Team move guide, choose Check team readiness to read the facts for your business. Enter your authenticator code when prompted.
- Review the active seats, pending invites and checklist states. In the illustrated test business the server returned 4 active seats and 1 pending invite.
Server-verified versus manual — the difference that matters:
| Kind | What it means | Examples in this assistant |
|---|---|---|
| Server-verified | The server was asked and answered; the step reflects the server's response | Seat and invite counts; the bots-and-routing step once the server confirmed the routing rule; the preflight result for destination setup |
| Manual confirmation | You tick a box yourself in the browser; nothing is checked with anyone | The five readiness confirmations in Record your cutover-and-rollback confirmations |
A manual tick is a planning record kept in your browser — it is never evidence that a provider accepted anything or that a switch happened.
The preflight itself reports named checks with plain results. In the illustrated businesses the server returned: organization exists (pass), 0 sender(s) connected (fail), no templates registered (fail), 0 webhook subscription(s), 0 active (fail), and a token check with no result for that session. Because the sender check failed, the destination-setup step showed blocked. Fix the underlying item (for example connect a sender) and choose Check destination again.
Destination links: where each step takes you
Each destination step has an Open link that leaves the assistant, opens the named area with its real screen, and you return to the assistant afterwards. The accepted evidence verified each link against these actual screens:
| Destination link | Screen you land on |
|---|---|
| Destination setup (onboarding) | Connect WhatsApp |
| Seats | Seats |
| Custom roles | Custom roles |
| Bots | Bots |
| Inbox routing | Inbox routing panel (assignment routing) |
| CRM | CRM |
| Message templates | Message templates |
| Staff inbox | Staff inbox |

Destination setup opens the Connect WhatsApp screen. Full-size image.

The Seats screen for reviewing who holds which seat. Full-size image.

The Message templates registry. Full-size image.
These links are reading and review steps. Opening them changes nothing by itself.
Check assignment routing
From the Inbox routing destination link:
- Open the routing panel with the routing toggle.
- Read the assignment mode shown for your business. In the illustrated business the server reported the mode round_robin (requests take turns among seats), and the panel displayed that same mode.

Assignment routing displayed as the server reported it: round robin. Full-size image.

The staff inbox area used to exercise the routing toggle. Full-size image.
Import text-template drafts
This step preserves your message wording as drafts. It is deliberately separate from any switching decision.
- Under Import text-template drafts, paste your template definitions into the definitions box. The preserved definition format looks like
locale_retention | utility | en | Keep {{1}} original— one definition per line. - Use Open template registry to visit the Message templates screen and compare.
- Choose Import drafts when the definitions are ready. In the accepted evidence the button stayed disabled while the box still contained the unchanged preserved definition — it becomes usable once the form represents an actual change.
Importing is not cutover. Import drafts only copies wording into drafts inside your business. It does not contact any messaging provider, does not register anything externally, and does not move your number. Use Check destination and cutover steps to review the checks and record your own confirmations.
Verify Meta routing and the destination Inbox
The assistant lists two checks for an authorized live cutover. The destination preflight reports saved connection and subscription facts. Use the checks below to confirm where real WhatsApp messages arrive.
- Check Meta conversation routing and incoming webhooks for the destination number. In Meta Business Settings, open WhatsApp accounts, identify the correct WhatsApp Business Account and select the exact destination number. Review Conversation routing for new customer messages and replies to the message types you use. Check whether the former provider still has messaging access. Record the existing routes and partner access for rollback, and review any Meta migration notice before changing either. The authorized business administrator performs the approved changes in Meta.
- Verify a real WhatsApp message and reply in the destination Inbox. From another WhatsApp account, send a fresh message to that number. Use Reply on the authorized outbound test message and send a second message. Confirm that both appear in the intended business's ConvoTide Inbox. Record the number, test time and result. If either is missing, review the exact number's routing, previous provider access and incoming webhook setup before accepting the cutover.
Use this procedure regardless of which WhatsApp provider you are leaving.
Record your cutover-and-rollback confirmations
Under Check destination and cutover steps, step 4 is labelled 4. Check and cutover in English (and जाँचें और स्विच करें / ਜਾਂਚੋ ਅਤੇ ਬਦਲੋ / तपासा आणि स्थलांतर करा / તપાસો અને સ્વિચ કરો in the other languages). Both the cutover-checklist and rollback-readiness steps link back to the readiness title so you can review the same summary from either side.
You then tick the five readiness confirmations yourself:
- Source preserved — you kept a recoverable copy.
- Roles reviewed — you checked seats and roles.
- Staff inbox exercised — you opened the staff inbox area.
- Cutover performed — you record that the switch itself is done.
- Rollback documented — you wrote down how you would undo it.

Step 4, Check and cutover, with the five browser-side confirmations. Full-size image.
These boxes are manual, browser-side records. Ticking Cutover performed does not perform, prove or trigger any provider-side switch — in the accepted evidence these confirmations were ticked with synthetic test data as a planning exercise, and the evidence explicitly records that no live provider migration occurred. Ticks are kept per business in this browser and survive a page reload; they are not a claim visible to your provider.
Once Roles reviewed is ticked, the seats-and-roles step changes from pending-manual to manual-complete.
When a step does not apply
Some businesses have no bots or routing. For the bots-and-routing step you can instead tick its not applicable choice:
- Ticking it changes the step from blocked to manual-complete.
- The choice is stored for that business only and survives a page reload.
- Use the matching clear control to undo it; after clearing, the step returns to blocked until a server check or a new choice changes it again.

A second business on a phone-width screen, with its own separate answers. Full-size image.
Switching businesses keeps answers separate
- From the assistant, go to the home area and choose Switch business.
- Pick the other business in the picker. The assistant reopens for that business.
- Its checklist starts from that business's own state. In the accepted evidence, a Roles reviewed tick recorded in business one was not present in business two, and a not-applicable choice recorded in business two was not present in business one. Each business also re-reads its own seat facts from the server.
If you open a fresh page with an explicit business link, that link decides which business is active — so always check the active business before trusting a checklist.
Recover, cancel and retry
- Interrupted check. If the destination check cannot complete (for example the connection drops), the assistant shows an error notice. In the accepted evidence, one check was deliberately interrupted: the error notice appeared, the destination-setup step returned to unverified, and — importantly — the server-verified bots-and-routing step kept its server-complete state and the manual confirmations stayed ticked. Nothing already established was lost.
- Retry. Choose Check destination again. In the evidence, the retry cleared the error notice and the checklist resumed.
- Cancel / undo your own records. Manual ticks and not-applicable choices each have a clear control; clearing returns that step to its previous state (pending-manual or blocked).
- Leaving and returning. Reload or leave and come back: your per-business confirmations and not-applicable choices are still there.

An interrupted check: error notice visible, established facts preserved. Full-size image.
Roles and refusals
- Administrator: sees the migration area and the full assistant; the server accepted its signed-in session during the destination check.
- Viewer: does not see the migration area at all — no navigation entry, no assistant. In the accepted evidence a viewer attempted the seats API directly anyway and the server refused it with status 403 and the message
SCOPE_DENIED — this action requires the "apikeys:manage" scope for your seat. The viewer could still use the language selector on the page they were on.

A viewer seat: the assistant is not offered and the underlying action is refused. Full-size image.
If you see a permission refusal, repeating the action will not grant access. Ask your administrator to review what your seat needs, or have an administrator perform the step.
Languages and phones
The assistant is fully translated. Switching the language changes every heading, button and step caption, including the step-4 caption:
| Language | Step 4 caption |
|---|---|
| English | 4. Check and cutover |
| Hindi | 4. जाँचें और स्विच करें |
| Punjabi | 4. ਜਾਂਚੋ ਅਤੇ ਬਦਲੋ |
| Marathi | 4. तपासा आणि स्थलांतर करा |
| Gujarati | 4. તપાસો અને સ્વિચ કરો |
When a non-English language is active, the English "Migration assistant" heading is not shown — the translated heading is used instead.

English on a phone-width screen. Full-size image.

Hindi on the same phone-width screen. Full-size image.
Evidence record (kept for honesty)
The checklist screenshots come from the accepted readiness journey
(CHIEF_ACCEPTED_COMPONENT_MIGRATION_JOURNEY, task 2992, main
0e740f345cae0ae9e646fac1f2df26ed1e64cb44), run in a browser against
PostgreSQL at 1440 px and 390 px. The later source and contact steps reflect
the signed-in Customer Owner readiness check, blank CSV downloads, and a
separate isolated browser and PostgreSQL import and reconciliation run using
synthetic CSV and XLSX files. These checks did not reconcile a real provider
export or perform a live cutover.
The full image-to-source mapping with SHA256 values is in the assets manifest. This guide reuses a 12-screenshot subset of the 23 accepted captures, chosen to cover navigation, facts, destinations, confirmations, recovery, business switching, roles and languages.