Developer Setup: Single Instance

This document shows you how to set up a single instance of the WhatsApp Business API client on a developer machine for testing purposes.

For a production setup, follow the relevant instructions listed in Production Setups.

Before You Start

You will need:

  • Docker
  • Docker Compose
    • It should be bundled with the Docker installation, but if not, you can install it.
  • A locally set up test account in a development environment
    • This is for fast development and to test new releases.

Initial Setup of the WhatsApp Business API Client

Perform the following steps to install a single instance of the WhatsApp Business API client on a developer system.

Step 1: Create a biz Directory for the Setup Scripts

Run the following code in your preferred location for the WhatsApp Business API client:

mkdir ~/biz; cd ~/biz;

Step 2: Get the WhatsApp Business API Client Configuration Files

The configuration files for the WhatsApp Business API client are located in the WhatsApp-Business-API-Setup-Scripts GitHub repository. You can set up your WhatsApp Business API client with either a MySQL or Postgres database instance.

Step 3: Set the WA_API_VERSION Environment Variable

The WA_API_VERSION environmental variable should be set to the current version using:

export WA_API_VERSION=current-whatsapp-version

Step 4: Start the WhatsApp Business API Client

To start the WhatsApp Business API client with 1 database container, 1 Webapp container, and 1 Coreapp container, run:

docker-compose up -d

The resulting output should look like the following:

Creating volume "biz_whatsappMedia" with local driver
Creating volume "biz_mysqlData" with local driver
Creating biz_db_1 ... done
Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

Step 5: Verify Containers Are Running

You can check that all containers have an UP state by running:

docker-compose ps

By default, the Webapp container will be running on port 9090 and the database container will be running on port 33060.

The resulting output should look like the following:

~/biz $ docker-compose ps
     Name                    Command               State                   Ports
-------------------------------------------------------------------------------------------------
biz_db_1       docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 6253/tcp
biz_waweb_1    /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

Step 6: Perform a Health Check

You can download and configure our Postman Collection for interacting with the WhatsApp Business API if you do not wish to use the command line.

You can perform a health check on the WhatsApp Business API client using an API call to the health node.

The resulting output should look like the following:

{
    "health": {
        "gateway_status": "unregistered"
    }
}

The response shows a gateway_status of unregistered as the gateway_status because the WhatsApp Business API client is not yet registered.

Step 7: Register the WhatsApp Business API Client

You can register your WhatsApp Business API client using an API call to the account node.

Step 8: Perform a Second Health Check

Perform another health check on the WhatsApp Business API client using an API call to the health node after completing registration.

The resulting output should look like the following:

{
    "health": {
        "gateway_status": "connected"
    }
}

A gateway_status of connected means the Coreapp container is able to connect to the WhatsApp server for checking contacts and sending messages.

Upgrading the WhatsApp Business API Client

There will be downtime during the upgrade process.

Backing up your current application settings before upgrading is highly recommended to ensure you can get back up and running quickly. Please follow the Backup and Restore documentation.

It is always recommended performing upgrades during your least busiest hours.

Step 1: Change the WA_API_VERSION Environment Variable to the New Version

The WA_API_VERSION environmental variable should be updated to the new version number using:

export WA_API_VERSION=new-whatsapp-version

Step 2: Restart the Docker Containers

Restart the Docker containers by running:

docker-compose 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 MySQL Database Users Upgrading to v2.23.x and Above

You can now make use of a database upgrade service that will let you upgrade your database while your application is still running to avoid downtime.

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:

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.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:

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:

WA_API_VERSION=new-whatsapp-version docker-compose up -d

Uninstalling the WhatsApp Business API Client

It is highly recommended to backup your current application settings before uninstalling. Please follow the Backup and Restore documentation.

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:

docker-compose 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

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:

docker-compose down -v

Troubleshooting

We recommend using WADebug for more effective troubleshooting. WADebug is a command line tool to help find any potential issues with the WhatsApp Business API setup and to make requesting help from WhatsApp support more effective.

In cases where WADebug cannot be used or running the tool returns errors run the following command to collect logs from all containers:

docker-compose logs > debug_output.txt

To collect the logs of a specific service, append the service name (waweb or wacore) to the docker-compose logs command:

docker-compose logs waweb > debug_output.txt

You can find the logs in the debug_output.txt file in the current directory.


This software uses code of FFmpeg licensed under the LGPLv2.1 and its source can be downloaded here.