Developer Setup: Single Instance

This guide will walk you through how to set up a single instance of the WhatsApp Business API Client on a developer machine.

This document covers:

Prerequisites

  1. Install Docker on your system.
  2. If Docker Compose is not bundled with your Docker installation, install it.
  3. It's recommended you set up a test account locally for fast development and to test new releases.

For a production setup, follow the instructions in Production Setup: Single Instance.

Initial Setup

  1. Create a biz directory to store the setup scripts:
    mkdir ~/biz; cd ~/biz;
  2. Download the docker-compose.yml and db.env configuration files to ~/biz: WhatsApp_Configuration_Files.zip.
  3. To start the WhatsApp Business API Client with 1 database container, 1 Webapp container and 1 Coreapp container, run:
    docker-compose up -d
    Example output:
    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
    
  4. 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.

    Example output:
    ~/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
    
    
  5. You can download and configure our Postman Collection to easily interact with the WhatsApp Business API.
  6. Perform a health check on the WhatsApp Business API Client. Example response:
    {
        "health": {
            "gateway_status": "unregistered"
        }
    }
    
    Because your WhatsApp Business API Client is not registered right now, you will see "unregistered" in the health status response.
  7. Follow the Registration documentation to register the WhatsApp Business API Client.
  8. Perform another health check after registration. You should now see connected status, which means the Coreapp container is able to connect to the WhatsApp server to check contacts and send messages. Example response:
    {
        "health": {
            "gateway_status": "connected"
        }
    }
    

Upgrading

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

The docker-compose.yml file has fields indicating container versions. For example:

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

To upgrade an installation:

  1. Change the version numbers in the docker-compose.yml file manually:
    services:
      ...
      wacore:
          image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.6}
      ...
      waweb:
          image: docker.whatsapp.biz/web:v${WA_API_VERSION:-2.21.6}
    
  2. Restart the Docker containers:
    docker-compose up -d
    Example output:
    biz_db_1 is up-to-date
    Recreating biz_wacore_1 ... done
    Recreating biz_waweb_1  ... done
    
  3. Alternatively, restart the Docker containers with environment variable WA_API_VERSION set to the new version:
    WA_API_VERSION=2.21.6 docker-compose up -d
    Example output:
    biz_db_1 is up-to-date
    Recreating biz_wacore_1 ... done
    Recreating biz_waweb_1  ... done
    

Uninstalling

It is highly recommended to backup your current application settings before uninstallation. 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

Example output:

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

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

docker-compose down -v

Troubleshooting

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

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

docker-compose logs > debug_output.txt

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

docker-compose logs waweb > debug_output.txt

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