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

Open the Migration assistant

  1. Sign in to the workspace, select your business, then open the Migration assistant.
  2. 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.
  3. 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).

Desktop view of the Migration assistant checklist with real team facts: active seats and pending invites counted, routing and bots steps shown with their states

The assistant after a destination check, with the team facts it read from the server. Full-size image.

Prepare your source exports

  1. 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.
  2. 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.
  3. 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

  1. 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.
  2. 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 (true or 1) and their source reference in whatsapp_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.
  3. 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.
  4. 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)

  1. Choose Check destination to read the saved account, sender, template and webhook records and see the ordered cutover checklist.
  2. Under Team move guide, choose Check team readiness to read the facts for your business. Enter your authenticator code when prompted.
  3. 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.

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

The Connect WhatsApp screen opened from the destination setup link

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

The Seats screen opened from the seats-and-roles link, listing team seats

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

The Message templates screen opened from the contacts-and-templates link

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:

  1. Open the routing panel with the routing toggle.
  2. 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.

Inbox routing panel showing the round-robin assignment mode read from the server

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

The staff inbox with its routing toggle, opened from the staff-inbox destination link

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.

  1. 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.
  2. Use Open template registry to visit the Message templates screen and compare.
  3. 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.

  1. 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.
  2. 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:

  1. Source preserved — you kept a recoverable copy.
  2. Roles reviewed — you checked seats and roles.
  3. Staff inbox exercised — you opened the staff inbox area.
  4. Cutover performed — you record that the switch itself is done.
  5. Rollback documented — you wrote down how you would undo it.

The cutover and rollback readiness section with the five manual confirmations

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:

Phone-width view of the assistant in a second business, with the not-applicable choice recorded for bots and routing

A second business on a phone-width screen, with its own separate answers. Full-size image.

Switching businesses keeps answers separate

  1. From the assistant, go to the home area and choose Switch business.
  2. Pick the other business in the picker. The assistant reopens for that business.
  3. 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

The assistant showing an error notice after an interrupted destination check, with earlier results still intact

An interrupted check: error notice visible, established facts preserved. Full-size image.

Roles and refusals

Phone-width page shown to a viewer seat: the migration assistant is absent and the direct request was refused with a scope-denied error

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.

Phone-width assistant in English showing the recoverable-copy, template-drafts and destination sections

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

Phone-width assistant in Hindi with translated headings, buttons and step captions

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.