Introducing the Messages API Sandbox

Introducing the Messages API Sandbox

Published April 08, 2020 by Martyn Davies

The Messages API Sandbox is a new way of developing and testing any application you want to build using WhatsApp, Viber, or Facebook Messenger via our Messages API.

The Sandbox allows you to link your own WhatsApp, Viber, or Facebook Messenger accounts so you can start sending and receiving test messages on your own devices as you build.

In this tutorial, we’re going to run through how you get everything set up.


To use the Messages API, you will need a Vonage Communications API account. If you don’t already have one, you can sign up for free and get an initial €2 credit.

Once you have your account, you’ll also need:

  • A smartphone with WhatsApp, Viber, or Facebook Messenger installed.
  • A command line or terminal application.

Whitelist Yourself

Head to the Messages API Sandbox in your Vonage API dashboard.

The first step is to whitelist your accounts. As the process is similar for all of the services supported, we’ll focus on WhatsApp in the External Accounts section.

External Accounts view in the Messages API Sandbox

Click the ‘Add to sandbox’ link to open the list of options. There are three ways to add a new account to the whitelist:

  1. Scan the QR Code with your camera to open WhatsApp with a pre-defined message.
  2. Send instructions to yourself, or another team member via email.
  3. Send a message directly from WhatsApp to the number specified using the unique phrase shown.

Whitelisting options for WhatsApp

Regardless of which method you choose, what you’re doing is linking the number and account ID you have set on your WhatsApp account to the API Key of your Nexmo account.

You’ll know it worked if the bottom of the whitelist section reads You have 1 user(s) whitelisted. If you don’t see this straight away, click the Refresh link.

If you would like to link a Viber or Facebook Messenger account, repeat the steps for each service.

Send Yourself a Message

Once your account is whitelisted, you can test it by sending yourself a message.

To do this, you can use Terminal on macOS and Linux or Command Line on Windows.

Copy the code for the service you have chosen from the code block at the bottom of the screen.

The CURL command required to send a WhatsApp message

It comes pre-filled with your API credentials, but you need to change the $TO_NUMBER to match the number of the account you previously whitelisted.

Paste the code into your Terminal application. Hit enter and wait for the response from the server; it should look something like this:


Then wait for the message to appear!

What the message looks like when it is received

Pretty cool, right?

Connect to Your Application via Webhooks

CURL is excellent and all, but we know you’re not here to send messages to yourself from the command line.

To give your application the ability to receive inbound messages from any of the supported services, you can set up an Inbound webhook.

The Webhooks Settings

To receive inbound messages, first ensure that your application has an endpoint to listen for messages on and that it can receive POST requests. You can call it whatever you like; we hear that /inbound is a popular choice.

Before you deploy your application to a server, you can use an app like Ngrok to make it accessible to the outside world. There are more details on how to set this up in our documentation.

It’s good to know what is happening to the messages your application sends. To help with this, we provide a Status webhook that reports any changes the occur along the delivery path.

For example, if you want to know if messages sent by your application are arriving, it would be reported via the status webhook using a delivered status. Although using this webhook is optional, it is an excellent choice to monitor it actively and record the data it sends you.

You Can Take It From Here

The Messages API Sandbox allows you to start working with WhatsApp, Viber, and Facebook Messenger quickly and easily. You can now connect any of these services to your new or existing applications, so what will you build with them?

Start by digging into the documentation for the Messages API.

If you’re looking for some inspiration, here are five other tutorials that we’ve created that might spark some ideas:

Whatever you’re building, we’re here for you if you need us. Head on over to the Vonage Developer Community Slack to pick up the conversation, share tips, and learn from others.

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at