Get started with the Twilio Sandbox for WhatsApp

The Twilio Sandbox for WhatsApp is a pre-configured environment available through the Twilio Console in which you can prototype sending outbound messages, replying to incoming messages, and configuring things like message delivery callbacks. You can use the Sandbox to test the functionality of the WhatsApp Business API with Twilio while you wait for Twilio to connect your WhatsApp Business Profile and your Twilio phone number.

Twilio pre-provisions the Sandbox with a Twilio phone number (+1-415-523-8886) that all Sandbox users share. However, other users who share the same Sandbox number won't receive your messages, only the ones who have opted in to your Sandbox.

The video below shows you how to use the Sandbox to send and receive WhatsApp messages.

To send or receive WhatsApp messages to an end-user from the Sandbox, you must first have any user join the Sandbox.

First, send the message "join <your Sandbox keyword>" to your Sandbox number in WhatsApp to join your sandbox. Your Sandbox keyword is a unique string; you can find it in the Twilio Console.

When Twilio receives the join message, we will reply with a confirmation to that user that they have joined the Sandbox.

Upon joining your sandbox, end users will only receive messages from your specific sandbox. To disconnect from the Sandbox, they can reply to the message from WhatsApp with the word "stop". You can switch to a different Sandbox by messaging "join <other sandbox keyword>".

The Sandbox expires three days after you join. After this time, you should re-join to continue testing.

One of the constraints of WhatsApp messaging is the 24-hour session or window. When an end-user sends your business a message, it kicks off a 24-hour window during which you can send them freeform outbound messages. Outside of this window, you must use templated messages to initiate outbound messaging with an end-user. (Check out our guide to WhatsApp notifications and templates.)

The Sandbox comes pre-configured with three templates for common use cases:

• Appointment Reminders: "Your appointment is coming up on {{1}} at {{2}}"
• Order Notifications: "Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details: {{4}}"
• Verification Codes: "Your {{1}} code is {{2}}"

(The double-bracketed numbers refer to your specific information in the notification message, such as "Your Twilio code is 1238432")

In the Sandbox, you can test making calls to Twilio's Programmable Messaging API to send one (or more!) of these outgoing messages.

People around the world use WhatsApp to engage with businesses, and your use case might involve replying to incoming messages from end users. You can use the Twilio Sandbox to explore replying to incoming WhatsApp messages.

When an end-user sends you a WhatsApp message, Twilio sends a webhook (a request to a URL that you specify) to your application. In the Sandbox, you can configure that webhook URL in the When a Message Comes in field:

Expand image

Most likely, you will set the incoming webhook URL to your web application's URL. When Twilio receives a WhatsApp message in your Sandbox, it will make a request to that URL. You can reply back to the message using TwiML, which is the language of instructions for how Twilio should reply to your message. (For a detailed walkthrough of setting up an application to reply with TwiML in the language of your choice, check out the Quickstart for the Twilio API for WhatsApp.)

You can test Twilio's real-time status update functionality for WhatsApp messages that you send and receive with the Sandbox. In the settings for your sandbox, add a URL in the Status callback URL field. Twilio sends a request to this URL each time your message status changes to one of the following: queued, failed, sent, delivered, read.

Expand image

By setting the Status Callback URL, you can automatically receive requests from Twilio with information about the delivery status of your WhatsApp message. For a more detailed walkthrough, check out the guide on Tracking the Message Status of Outbound Messages. The messaging channel is different, but the principles are the same. You'll want to remember to put the URL for your status callback in the Sandbox.)

Because the Twilio Sandbox for WhatsApp is for rapid prototyping rather than production-ready uses, it does have a few limitations:

• You can only message end users who have joined your Sandbox. Messaging other users will fail with Error 63015.
• The Twilio Sandbox supports functional testing, but not load testing of profile traffic.
• Sandbox numbers can only send 1 message every 3 seconds.
• Sandbox numbers are Twilio numbers. They display the Twilio logo.
• You can only use pre-registered templates with the sandbox for outbound messages sent outside a WhatsApp session. (Learn more about using and registering WhatsApp message templates.)
• The Sandbox session expires three (3) days after joining. After this, follow the steps described above to rejoin.

There is no limit to the number of messages you can send via Twilio Sandbox, nor any limit on how long you can use the Sandbox. Twilio bills Sandbox messages like regular messages, per pricing for Twilio API for WhatsApp.

After this introduction to the Twilio Sandbox for WhatsApp, you can get started prototyping integrating WhatsApp with Twilio Programmable Messaging and your application.

You can also read more about some of the concepts covered in this document following the links below:

• The WhatsApp Quickstart: A step-by-step walkthrough of the Sandbox, for sending and receiving your first WhatsApp message
• Getting started to WhatsApp and how to onboard your first WhatsApp Sender
• Send and receive WhatsApp media messages