WhatsApp Business API Postman Collection

Postman is a popular tool to help test and develop APIs. To make it more convenient for developers integrating with the WhatsApp Business APIs, we've developed a Postman collection that contains the full set of API calls.

This document shows you how to set up the WhatsApp Business API Postman Collection and use it to make requests of the WhatsApp Business APIs.

Before You Start

You will need:

Step 1: Set up the WhatsApp Business API Postman Collection

Once you have Postman up and running, click Import and select the two JSON files in the Postman Collection package from GitHub. After it is imported, you should see WhatsApp Business API listed under Collections and be able to select WABiz Developer from the Environment drop-down menu in the top right corner.

WABiz Developer Environment

Step 2: Configure the WABiz Business Environment

Postman offers a configurable environment, which is essentially a set of key-value pairs, allowing you to create commonly used variables that can be referenced across multiple requests. See the Postman documentation on managing environments for more information.

The preconfigured WABiz Developer environment contains a non-exhaustive set of variables that are referenced by the collection. It's important to update some of these variables with your own values.

You can edit the environment's variables by clicking the little eye button next to the Environment drop-down menu, then clicking Edit.

Edit the WABiz Developer Environment

If you want to make this even more convenient, you can write post-request scripts that will parse values from the API responses and update the corresponding environment variable. A Postman blog post on Extracting Data from Responses and Chaining Requests shows you how to do this.

Webapp hostname

The most important variable to update is URL, which represents the Webapp. All of the requests will reference this variable as {{URL}}, so it's important it is set to the correct Webapp hostname.

WABiz Developer Environment Variables

Authentication Token

In order to make API calls from the collection, you will need to obtain and replace these values with valid ones. The login endpoint will generate and return a authentication token as a response. Take the returned auth token and update the appropriate environment variable with it so subsequent API calls can use it for authentication.

Step 3: Turn off the SSL Certificate Verification Setting

The WhatsApp Business APIs require the use of HTTPS. Postman understands this and will try to do an SSL certificate handshake. You can bypass this by using an insecured HTTPS.

Go Postman > Preferences > General tab, and turn off the SSL Certificate Verification setting.

Note: This is particularly important when testing with MacOS Catalina (10.15) due to the way Apple manages SSL certificates at the operating system level.

SSL Certificate Verification Setting

Step 4: First Time Login

If this is the first time sending API calls, you need to log in and change the admin password. Update the AdminUsername, AdminPassword environment variables to their factory defaults of admin and secret and the NewAdminPassword environment variable to whatever your chose.

Set Authorization to Basic Auth and the username/password variables as shown below. In the Body tab, the new_password value should be filled from variable NewAdminPassword. Click Send to send request and get the auth token response.

Authorization Settings

Once you get a successful response, copy the token value into your AdminAuthToken environment variable and change the AdminPassword environment variable to match the new password you just set. Click Update to save the values.

Update Login Variables

Now you have an auth token that will let you perform admin tasks. The Postman collection uses the variable in its headers so you don't have to re-enter it every time.

Remove the new_password property from the Body tab of the Login-Admin API call template.

Step 5: Registration

See the Registration documentation for more information about the registration process.

Under the WhatsApp Business API collection, select 02-Registration > Request-Code.

Before making the API call, make sure the crucial registration variables are set correctly in the environment list in the Body tab:

  • RegistrationRequestCountryCode
  • RegistrationRequestPhoneNumber
  • RegistrationRequestMethod
  • RegistrationRequestVNameCert — The base64 certificate string you get from your WhatsApp Account in the Facebook Business Manager.
  • TwoStepPIN — If Two-step Verification is enabled.

Make sure there are no carriage returns or trailing whitespace in the base64 certificate value you copy in. It should be a long string of characters with no spaces at the end.

After you succeed at a Request-Code API call, you will get a code by your selected method. Update the RegistrationRegisterCode environment variable with the received code. Select 02-Registration > Register-Account in the collection list and make the API call. When this succeeds with 201 Created, your phone number is registered, and you are ready to use the instance for checking contacts and sending messages.

Step 6: Send Test API Calls

You're now set to choose any of the API calls in the collection and start firing! Start with a login API call to ensure your auth token is up-to-date for use in all other API calls.

Feel free to edit the API calls in any way you'd like. The intention is help you test the WhatsApp Business APIs and their responses more easily.

API Request and Response