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.
Once you have your account, you'll also need:
- A smartphone with WhatsApp, Viber, or Facebook Messenger installed.
- A command line or terminal application.
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.
Click the 'Add to sandbox' link to open the list of options. There are three ways to add a new account to the whitelist:
- Scan the QR Code with your camera to open WhatsApp with a pre-defined message.
- Send instructions to yourself, or another team member via email.
- Send a message directly from WhatsApp to the number specified using the unique phrase shown.
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.
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!
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
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.
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:
- Save Received SMS Messages with Airtable and Node.js—You could change this to store received WhatsApp, Viber or Facebook Messenger Messages.
- Discover your Twitter Positivity Score—You could build on this React example and have it send the score via Viber or WhatsApp instead.
- Scrape the Web and Send SMS Updates—You could take this example app and have it send the results via WhatsApp.
- Real Time SMS Translations with Node, React, and Google—Why not add to this application and get it to translate SMS, WhatsApp or Facebook Messenger messages?
- Send and Receive SMS Messages with Node.js and Azure Functions—Try amending this Azure Function so it sends Viber messages instead of SMS.
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.