WADebug: Troubleshooting Tool for WhatsApp Business API

Current version: 0.1.4

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.

WADebug's support for different types of setups is shown below. Run checks refers to the commands that run various actions to verify the WhatsApp Business API client setup. Retrieve logs refers to the command to retrieve all container logs.

Type of SetupRun checksRetrieve logs

On-premise Single Instance

Supported (instructions)

Supported (instructions)

On-premise High Availability /MultiConnect

Not Supported

Supported (instructions)

Kubernetes

Not Supported

Not Supported

AWS

Not Supported

Not Supported

This document covers:

Install WADebug

WADebug is a command-line tool written in Python, compatible with both Python 3 and 2.7. We recommend Python 3. Install it using pip:

pip3 install wadebug

To upgrade:

pip3 install wadebug --upgrade

To uninstall:

pip3 uninstall wadebug

To validate you have wadebug installed, you can run:

wadebug --help

Run checks

WADebug has a set of actions to verify a WhatsApp Business API setup. By default, it runs all the actions available. If there's any problem or warning status returned, the description, details and possible mitigation methods will be shown to help you troubleshoot your setup. You will also be reminded of how to upload logs to Facebook if you need help.

To use the tool, run the following command from the machine hosting WhatsApp Business API docker containers:

wadebug

If an action results in wadebug_error, this indicates that there was an issue with the tool itself. If you encounter such an issue, please report this bug via Direct Support



Configuration File

WADebug requires a configuration file (wadebug.conf.yml) in the current directory to run full checks.

When running wadebug without the config file, the tool will prompt to create a skeleton file for you to fill out the configuration values. If no configuration file can be found or no configuration values are set, some actions will be skipped due to lack of information.

Sample configuration file:

  
    # configurations related to the MySQL database
    db:
      # hostname of the MySQL database
      host: # for example, "0.0.0.0"
      # host port that the MySQL database uses
      # to connect to database container created by docker-compose scripts, use 33060
      port: # for example, 33060
      # username to connect to the MySQL database
      user: # for example, "root"
      # password of the username that is used to connect to the MySQL database
      password: # for example, "your_database_password"

    # configurations related to WhatsApp Business API
    webapp:
      # url accessible from the host running wadebug
      baseUrl: # https://localhost:9090
      # WhatsApp Business API user account credentials to call Support API
      user: # for example, "wadebug"
      # WhatsApp Business API user account credentials to call Support API
      password: # for example, "secretdebugger"
  

Listing possible actions

To check available actions, you can run:

wadebug ls

Partial run

To run only a subset of available actions, do:

wadebug partial check_software_version check_mysql_version

JSON mode

wadebug offers two modes: interactive mode and JSON mode.

Interactive mode is the default mode, when this mode is used, you will see visualized tables of results, notices, be prompted to create configuration file etc.
JSON mode is useful when you want to integrate wadebug into an automation pipeline to validate WhatsApp Business API setup periodically or every time you upgrade the WhatsApp Business API version for example.

To run wadebug in JSON mode, pass --json flag to any available wadebug command:

wadebug --json

Valid JSON response will be returned:

{
   "containers_status":{
      "class":"CheckContainersAreUp",
      "user_facing_name":"containers_status",
      "result":"OK"
   },
   "check_mysql_connection":{
      "class":"CheckMySQLConnection",
      "user_facing_name":"check_mysql_connection",
      "result":"OK"
   },
   "check_software_version":{
      "class":"CheckSoftwareVersion",
      "user_facing_name":"check_software_version",
      "result":"OK"
   },
   "check_mysql_version":{
      "class":"CheckMySQLVersion",
      "user_facing_name":"check_mysql_version",
      "result":"OK"
   },
   "check_network":{
      "class":"CheckNetworkAction",
      "user_facing_name":"check_network",
      "result":"OK"
   },
   "check_mysql_permissions":{
      "class":"CheckMySQLPermissions",
      "user_facing_name":"check_mysql_permissions",
      "result":"OK"
   },
   "check_mysql_password":{
      "class":"CheckMySQLPassword",
      "user_facing_name":"check_mysql_password",
      "result":"OK"
   },
   "check_db_settings_exist":{
      "class":"CheckDbSettingsExist",
      "user_facing_name":"check_db_settings_exist",
      "result":"OK"
   },
   "check_webapp_port":{
      "class":"CheckWebappPortAction",
      "user_facing_name":"check_webapp_port",
      "result":"OK"
   }
}    
    

Usage data collection and opt-out

Every time wadebug runs, usage data (including actions run and results returned) will be sent to Facebook to help improve the tool as well as accelerate WhatsApp support process via Direct Support.

If you don't want to share usage data with Facebook when using the tool, run wadebug with the flag --do-not-send-usage

wadebug partial check_network --do-not-send-usage

Keep in mind that, while you will still see troubleshooting results locally, your experience interacting with our support will be degraded.

Retrieve logs

wadebug provides a convenient way to retrieve all container logs, and optionally send them to Facebook to assist our support team's investigation.

To retrieve and save logs under wadebug_logs/ in the current directory:

wadebug logs

To send them to Facebook, you can append the --send flag. You will receive a run_id as part of the response, which you can reference in Direct Support for quicker investigations. :

wadebug logs --send

Retrieving logs from High Availability/Multiconnect setup

For High Availability/Multiconnect mode where containers are installed on one or multiple hosts, you need to log onto each host, install WADebug and run the wadebug logs commands mentioned above.

Ask for help

If you need help in troubleshooting WhatsApp Business API setup, please open a Direct Support ticket with the run_id returned after you run wadebug. This allows us to see a report of the actions run and the respective results.

A report of this run has been uploaded to Facebook.  You can reference run_id (A5jedVKsdI_ZojRwL1_-MOd) in Direct Support (https://business.facebook.com/direct-support) tickets
  	

Container logs are very useful for troubleshooting, to collect and send container logs to Facebook, please run wadebug logs with the --send flag.

wadebug logs --send

and provide the run_id returned

Container logs have been uploaded to Facebook.  You can reference run_id (AcClyxkRJk3w1dEr8OAmsTn) in Direct Support (https://business.facebook.com/direct-support) tickets
  	

Change Log

September 3, 2019 (v0.1.4)

  • A new and cleaner UI for WADebug
  • [Bug Fix] Fix wrong port printed when there's an error connecting in check_network action
  • [Bug Fix] Add missing MySQL privilege requirements in check_mysql_permissions action

April 26, 2019 (v0.1.3)

  • Add new configuration file items required by new actions
  • Add webhook health checks
  • Add WADebug upgrade prompt when a new version is available on PyPi
  • Add support endpoint response to uploaded logs for easier troubleshooting
  • WADebug crash logs are now uploaded to to Facebook

Dec 28, 2018 (v0.1.2)

  • Limit the size of logs retrieved
  • Capture coreapp coredumps in case of crashes
  • Add new command to retrieve logs without upload
  • Add enum34 as a required module for < Python 3.4

Oct 23, 2018 (v0.1.1)

  • Initial release