Migration

If you have an existing setup of the WhatsApp Business API client and you want to migrate to a new setup using the same phone number, this document shows you how to identify changes to be made and what you need to do about them.

Before You Start

• Backup is the most important step of the migration.
• You don’t have to re-register your phone number after migration. You can start messaging as soon as the migration is complete.
• The new setup must have the same number of shards as the old setup. You cannot scale up or scale down during migration. If your old setup is configured with an X number of Masters and a Y number of Coreapps, the new setup must have exactly the same number of Masters and Coreapps. If there is a mismatch in the number of Masters and Coreapps before and after migration, the migration will fail.
• Try migrating a test account before migrating a production account.
• Prepare for downtime and do not send messages during the migration. Regardless of the migration option, there will be downtime. Only after the migration is complete resume sending messages.

Settings Migration

Migrating the WhatsApp Business client settings preserves the application settings, the registration information and the encryption keys. Messages and authentication token info are not migrated.

Because the amount of data needing to be transferred between machines is minimal, there is only small amount of downtime.

Step 1: Install a new setup

Set up your new WhatsApp Business API client using the Installation documentation.

Step 2: Obtain a new authentication token for the new setup

The current authentication token will not be valid in new environment. Log in to the new setup to obtain a new authentication token.

Step 3: Cleanup

• [Optional] Disable two-step authentication. This is helpful when the two-step authentication code is forgotten and you need to re-register. Though re-registration is not required for a smooth migration, you may be forced to re-register if the backup and restore fails for some unknown reason. Follow the instructions to disable the two-step authentication code.
  Note: If you are confident that your two-step authentication code is correct, this step is optional.
• [Optional] Reset any Webhooks. If Webhooks are set up to receive inbound notifications and the Webhook server is also getting changed during migration, disable the old Webhook server in the Application Settings.
  Note: This step is optional if you are not changing the Webhook server after the migration.

Step 4: Back up the settings from the current setup

Use the current authentication token to back up the settings data from the current WhatsApp Business API client.

Step 5: Uninstall the current setup

This causes a downtime for messaging. To minimize it, make sure the WhatsApp Business API client is ready to run in the new location. Refer to the Uninstalling section of the respective Installation guide for instructions. Make sure you are only uninstalling the WhatsApp Business API client, which includes the Docker containers of the Coreapp, Webapp and Master; do not delete the database.

Step 6: Restore the settings in the new setup

Log in if you're not already using a new authentication token, and perform a restore on the new setup.
Your new WhatsApp Business API client should be running with all the required information and ready for messaging. The most important thing to remember is re-registration of the WhatsApp account is not required if the settings are backed up and restored properly.

Step 7: Perform a health check

Perform a health check and send a test message to verify the WhatsApp Business API client is working.

Step 8: [Optional] Enable two-step verification

If you disabled it in Step 3, re-enable two-step verification now. This provides additional security for your WhatsApp account.

Step 9: Set up Webhooks

Set up your Webhooks to enable inbound notifications.

Step 10: Drop the old database

Your old database contains the data of your old settings, old messages and old auth tokens. If you want to recover any of this data in future, do not drop the old database. Once you decide to drop the database, make sure the WhatsApp Business API client has been running for at least 14 days and messaging is working well before deleting it.