Upgrade the WhatsApp Business API Client

Recommendations

• Upgrade during the hours with the least amount of traffic
• Back up your current application settings before upgrading

For a Single Instance

Step 1: Update the Version

Update the WA_API_VERSION environmental variable to the new version number using:

export WA_API_VERSION=new-whatsapp-version

Step 2: Restart the Docker

Restart the Docker containers by running:

~/biz $ docker-compose -f docker-compose.yml -f network-waent.yml up -d

The resulting output should look like the following:

biz_db_1 is up-to-date
Recreating biz_wacore_1 ... done
Recreating biz_waweb_1  ... done
  
  

For Multiple Instances

To upgrade multiple instances SSH to each Webapp, Master, and Coreapp host and execute the following scripts:

Replace your-webapp-hostname, your-master1-hostname, your-master2-hostname, your-coreapp1-hostname, your-coreapp2-hostname, username@$host, /your-local-path/, and NEW-WA-API-VERSION with your environment names.

# ssh to each Webapp host, execute scripts with new WA_API_VERSION to upgrade Webapp on the host
for host in your-webapp-hostname; do
  cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=NEW-WA-API-VERSION docker-compose -f /your-local-path/prod-multiconnect-compose.yml -f /your-local-path/network-waent.yml up -d"
  ssh username@$host $cmd waweb
done 
# ssh to each Master host, execute scripts with new WA_API_VERSION to upgrade Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=NEW-WA-API-VERSION docker-compose -f /your-local-path/prod-multiconnect-compose.yml -f /your-local-path/network-waent.yml up -d"
  ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts with new WA_API_VERSION to upgrade Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=NEW-WA-API-VERSION docker-compose -f /your-local-path/prod-multiconnect-compose.yml -f /your-local-path/network-waent.yml up -d"
  ssh username@$host $cmd wacore
done

MySQL Upgrade

For MySQL database users upgrading to v2.23.x and later, you can upgrade your database while your application is runnin.

Step 1: Download the configuration file

The dbupgrade-compose.yml file has fields indicating the container version.

Example:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

Step 2: Start the container

To upgrade an installation, start the dbupgrade-service container with the WA_API_VERSION environment variable set to the latest version:

~/biz $ WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml -f network-waent.yml up -d

For mutliple instances:

EXTERNAL_HOSTNAME=$host_to_upgradedb WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml -f network-waent.yml up -d

Note: If you are using an orchestration that restarts the container upon exit irrespective of the exit code, start the service with the EXIT_ON_SUCCESS environment variable set to FALSE in order to avoid exiting the container when the exit code is 0.

Step 3: Allow the upgrade to finish

If the database upgrade is successful, the container will exit with code 0. You can use the following Docker command to track the status:

~/biz $ docker wait your-database-upgrade-container-name

This will output the exit code of the dbupgrade-service container.

Step 4: Restart the Coreapp and Webapp containers

Restart the Coreapp and Webapp Docker containers with the WA_API_VERSION environment variable set to the latest version:

~/biz $ WA_API_VERSION=new-whatsapp-version docker-compose -f docker-compose.yml -f network-waent.yml up -d

For multiple instances:

EXTERNAL_HOSTNAME=$host_to_upgradedb WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml -f network-waent.yml up -d

For WhatsApp Business API Client Users Upgrading to Version 2.29.3 and Above

If you are upgrading from v2.29.1, v2.29.2 or encountered problems during upgrade to those versions and had to roll back for stability, we recommend you upgrade to v2.29.3, then run the following command on the Webapp Docker container:

chown -R root your-media-directory/incoming your-media-directory/outgoing your-media-directory/shared

Unless you have changed it, the default media directory is /usr/local/wamedia.

Note:

• Since this command can take a while to complete based on pre-existing media volume size, we recommend this command be initiated as soon as you upgrade during the maintenance window.
• This command only modifies ownership of media volumes in the background (There is no impact/downtime for media operations or latency/performance while it is running).
• This is a one-time only upgrade path to fix backward compatibility issues in v2.29.1 and v2.29.2.

Uninstall the Client

Recommendations

• Back up your current application settings before upgrading

If you need to reset your development environment by removing all containers, run the following command from the directory containing the docker-compose.yml file:

~/biz $ docker-compose -f docker-compose.yml -f network-waent.yml down

The resulting output should look like the following:

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Stopping biz_db_1     ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done
Removing biz_db_1     ... done
Removing network waent

To get rid of all volumes defined in the docker-compose.yml file in addition to the containers, run the down command with the -v parameter:

~/biz $ docker-compose down -v