WhatsApp Business API Sandbox

The sandbox is a way for you to try out the WhatsApp Business API even without access to the production setup. The sandbox gives you an experience of most of the features and functionalities of the WhatsApp Business API. Please note that the purpose of the sandbox is testing, and it should not be used for sending messages to your customers.

This document covers:

Getting a Sandbox

A sandbox account can be created via your Business Manager account. See the Create a WhatsApp Business API Sandbox Account Help Center article for instructions.

It should take about 30 minutes for the sandbox to be activated. Once it has been activated, the Settings tab of the sandbox account will show the details of sandbox phone number, the hosted WhatsApp Business API Client URL, and the username and password. Also displayed are the date and time that the sandbox will expire.

You can set up one sandbox per Business Manager, and each sandbox is only active for 30 days. If you need to continue testing after that, you can request a new sandbox when the old one expires.

Using the Sandbox

Please note that anything sent using the sandbox is not end-to-end encrypted as WhatsApp hosts the WhatsApp Business API client.

You can use the sandbox to try the Messaging and Account Management features of the WhatsApp Business API. There are two set of tools for testing these functionalities:

  • The Web Business Tool, a graphic interface accessed by clicking on the sandbox URL in the Settings tab, or
  • The WhatsApp Postman Collection, a third-party program for sending API calls.

The login information for both of these is the username and password found under the sandbox's Settings tab.

The sandbox is created with a random default password for the admin user. If you would like to change the password, you will need to use the Login-Admin template found under 00-Users in Postman and follow the first login procedure.

The Settings tab will continue to display the original password once you have changed the password due to restrictions in the system, but you will need to use the new password when you wish to login.

Sandbox Settings

Messaging

Opt-in

You can use the WhatsApp Business API sandbox to send and receive messages with up to 5 phone numbers. These numbers need to opt-in to the sandbox in order to receive messages. At this time, only 5 numbers can join a sandbox. After 5 numbers have opted-in, any additional numbers you try to add won't receive any messages or trigger callbacks.

To opt-in a number, send Join from the phone number to the sandbox's phone number, which is found in the sandbox's Settings tab in the Business Manager. You can stop receiving messages from a sandbox by sending Leave to the sandbox number.

Sandbox Messaging

Sending and Receiving with the Web Business Tool

Please note that the WhatsApp Business API Sandbox's Web Business Tool currently only works in Chrome.

Once a number has opted-in to the sandbox, you will see it in the Messaging tab of the Web Business Tool, and the 2. Try the API section will reveal the various messaging types available to you: Template, Text, Document, and Media.

Any messages sent thru the Web Business Tool will be displayed in the right side column under the Messaging tab. Please note that only the last 50 messages will be displayed at a time; they are also not retained in the Web Business Tool long term and will disappear if the page is refreshed.

Try the API
Templates

The Web Business Tool has a selection of test template message types for you to send including account balance, booking confirmation, ordering notification, and a blank template. The account balance, booking confirmation, and order notification templates are already populated with example text, variables, and default values. These pre-defined templates are only available with the en language setting.

  1. Select the Template tab.
  2. Select a template message type from the Template type drop-down menu. All the related fields will auto-populate with example data.
  3. Click Send Message. Information about the template message will appear to the right under the phone number it was sent to.
Text

You can test sending freeform text messages by doing the following:

  1. Select the Text tab.
  2. Enter the text message you wish to send in the text box.
  3. Click Send Message. The text message will appear on the right side of the dashboard under the phone number it was sent to.
Document

You can test sending document files by doing the following:

  1. Select the Document tab.
  2. Click on Click here to select and attach file.
  3. Select the document file you wish to send.
  4. Click Send Message. The document message will appear to the right under the phone number it was sent to.
Media

You can test sending photos by doing the following:

  1. Select the Media tab.
  2. Click on Click here to attach photos.
  3. Select the media file you wish to send.
  4. Add a caption to the text box.
  5. Click Send Message. The media message will appear to the right under the phone number it was sent to.

Sending and Receiving with the WhatsApp Postman Collection

Postman is a third-party tool that WhatsApp has developed an API collection for in order to make sending API calls easier.

The Postman app requires the acquisition of an authentication token to make API calls. You can obtain an auth token with a login API call using the Login-User template found under 00-Users.

Templates

You need to use the namespace and element information of the example template messages in the Web Business Tool to send a test template message from Postman using the Send-HSM-Messagetemplate under 04-Messages.

See the Sending Message Templates documentation for more information on the fields involved in sending template message API calls.

Text

Use the Send-Text-Message template found under 04-Messages to send test text messages.

See the Sending Text Messages documentation for more information on the fields involved in sending text message API calls.

Documents and Media

To send document and media messages, you must first upload the file you wish to send in the message using the Upload-Media template under 06-Media. The response will include the ID you need to send the message using either the Send Image-Message-JPEG or Send-Doc-Message-PDF template under 04-Messages.

See the Sending Media Messages documentation for more information on the fields involved in sending media message API calls.

Account Management

Account Settings

Using Account Settings you can set your account's About information and profile picture. You can also set Business information such as address, description, email address, and website URL.

Sandbox Account Settings

In Postman, you can find the Profile and Business Profile templates under 01-Settings.

See the /v1/settings/profile node and /v1/settings/business/profile endpoint documentation for more information.

Application Settings

Application Settings affects the the behavior of the WhatsApp Business API Client allowing you to set things like intervals, webhooks, and auto-download settings.

Sandbox Application Settings

In Postman, you can find the Application and Two-Step Verification templates under 01-Settings.

See the /v1/settings/application endpoint documentation for more information.

Please note that the default URL displayed in the Webhooks URL field allows the Web Business Tool to display the messages you send and receive in the Messaging tab, so we do not recommend changing it if you are relying on the Web Business Tool for your testing.

Limitations

Due to the nature of the WhatsApp Business API Sandbox, there are some features that are not available or are restricted. The features that are not available in the sandbox include:

  • Backup and recovery actions
  • Setting up two factor verification
  • Downloading a SSL certificate

Feature restrictions include:

  • The number of groups you are permitted to create is limited to 5.
  • Three phone numbers may be checked with the contacts endpoint at a time.