Migration

If you have an existing setup of the WhatsApp Business API client with a database and you want to migrate both client and database to a new setup using the same phone number, this guide will help you identify changes to be made and what you need to do about them.

This document covers:

Before Starting Migration

  1. Backup is the most important step of the migration.
  2. You don’t have to re-register your phone number after migration. You can start messaging as soon as the migration is complete.
  3. 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.
  4. Try migrating a test account before migrating a production account.
  5. There will be downtime. How long is dependent on the of migration option, but every migration has downtime.

Migration Options

There are several migration options depending on the amount of data you want to migrate. Please choose the option that fits best into your needs.

Data preserved for each migration option

Option 1Option 2Option 3

Settings

App Settings

Registration

Encryption Keys

Messages

Messages

Callbacks

Contacts

Auth Tokens

API user data

API auth tokens

Typical use case and downtime of each migration option

This table describes typical use cases of each migration option and related downtime. These are only typical use cases, you may choose the type of migration option according to your choice.

General Use CaseDowntime

Option 1

A solution provider moving an end-client to your platform and you want to persist only settings data

This option has the lowest downtime compared to other options because the amount of data needing to be transferred between machines is minimal.

Option 2

A solution provider moving an end-client to your platform and you want to persist both settings and messages data

This option has more downtime compared to option 1 because both messages and settings data needs to be transferred between machines. This data can get quite large depending on the business.

Option 3

A direct client of WhatsApp managing the WhatsApp Business API client by yourself and you are moving the WhatsApp Business API client and data to a different machine

This option has the highest downtime compared to other options because the client data needs to be transferred between machines in its entirety. This data can get quiet large depending on the business.

Option 1: Settings Only

In a Settings Only migration, only the settings information is backed up and restored. Messages and authentication token info are not migrated.

  1. Install a new setup.
    Set up your new WhatsApp Business API client using the Installation documentation.
  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.
  3. Cleanup
    • [Optional] Disable two-factor authentication. This is helpful when the two-factor 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-factor authentication code. Note: If you are confident that your two-factor 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.
  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.
  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.
  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.
  7. Health check
    Perform a health check and send a test message to verify the WhatsApp Business API client is working.
  8. [Optional] Enable two-factor verification.
    If you disabled it in step 3, re-enable two-factor verification now. This provides additional security for your WhatsApp account.
  9. Set up Webhooks.
    Set up your Webhooks to enable inbound notifications.
  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.

Option 2: Settings and Messages

In a Settings and Messages migration, both the settings information and messages are backed up and restored. Authentication token information is not migrated.

Be wary of the amount of data that needs to be transferred to a different machine. Since more data needs to be backed up and restored, there is relatively more downtime than with option 1. The total downtime will vary depending on the amount of data being transferred and network latencies.

  1. Cleanup
    • [Optional] Disable two-factor authentication. This is helpful when the two-factor 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-factor authentication code. Note: If you are confident that your two-factor 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. This is the first step where messaging begins to experience downtime. Note: This step is optional if you are not changing the Webhook server after the migration.
  2. 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; do not delete the database.
  3. Back up the database.
    Back up all the databases except for waweb, which contains users/authentication data, using a utility such as mysqldump or pg_dump from the current WhatsApp Business API client. Note: It is important to exclude waweb if you are a solution provider migrating a business to or from your platform. You may not want to carry forward or hand over currently stored authentication tokens and users info.
  4. Restore the database.
    Restore the database using a utility such as mysqldump or pg_dump to the new WhatsApp Business API client.
  5. Install a new setup.
    Set up your new WhatsApp Business API client using the Installation documentation. Make sure to point your database to the restored location from step 4.
  6. 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.
    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 database is backed up and restored properly.
  7. Health check
    Perform a health check and send a test message to verify the WhatsApp Business API client is working.
  8. [Optional] Enable two-factor verification.
    If you disabled it in step 1, re-enable two-factor verification now. This provides additional security for your WhatsApp account.
  9. Set up Webhooks.
    Set up your Webhooks to enable inbound notifications.
  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 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.

Option 3: Full Migration

In a Full migration, all the settings, messages and authentication tokens are backed up and restored.

This option may seem best of all, but be wary of the amount of data that needs to be transferred to a different machine. Since more data needs to be backed up and restored, there is relatively more downtime for this option than both option 1 and option 2.

  1. Cleanup
    • [Optional] Disable two-factor authentication. This is helpful when the two-factor 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-factor authentication code. Note: If you are confident that your two-factor authentication code is correct, this step is optional.
  2. Back up your current authentication token.
    The maximum validity of token is 7 days. Please make sure your token has enough time for you to perform the migration.
  3. 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; do not delete the database.
  4. Back up the database. Back up the database using a utility such as mysqldump or pg_dump to capture the settings, messages and auth tokens data. If you are migrating only the WhatsApp Business API client but not the database, this step is optional.
  5. Restore the database.
    Restore the database using a utility such as mysqldump or pg_dump to the new WhatsApp Business API client.
  6. Install a new setup.
    Set up your new WhatsApp Business API client using the Installation documentation. Make sure to point your database to the restored location from step 5.
    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 data is backed up and restored properly.
  7. Health check
    Perform a health check and send a test message to verify the WhatsApp Business API client is working.
  8. [Optional] Enable two-factor verification.
    If you disabled it in step 1, re-enable two-factor verification now. This provides additional security for your WhatsApp account.
  9. Set up Webhooks.
    Set up your Webhooks to enable inbound notifications.
  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 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.