Martyn Davies

Director of Developer Education

Former Director of Developer Education at Vonage. With a background as a creative developer, product manager, and hack day organizer, Martyn has been working as a technology advocate since 2012 hav...

[Read more]
< Announcement />

Introducing the Messages API Sandbox

Last updated on Apr 19, 2021

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.


Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Screenshot of new Meetings API session in progress
Start developing in minutes with free credits on us. No credit card required!

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
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
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
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
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
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.