Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Get started with the Twilio Sandbox for WhatsApp


(warning)

Warning

Looking for a step-by-step walkthrough to get started with the WhatsApp Business API with Twilio? Check out our Quickstart guide, which is available in multiple programming languages.

With the Twilio Sandbox for WhatsApp, you can prototype with WhatsApp immediately, without waiting for your Twilio number to be approved for WhatsApp.

For more information about the onboarding process, read about connecting your WhatsApp Business Profile with your Twilio number.


What is the Twilio Sandbox for WhatsApp?

what-is-the-twilio-sandbox-for-whatsapp page anchor

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. While you wait for your WhatsApp Business Profile to be connected with your Twilio phone number, it's a quick way to test out the functionality of the WhatsApp Business API with Twilio.

The Sandbox is pre-provisioned with a Twilio phone number (+1-415-523-8886) that is shared across all sandbox users. 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.

(warning)

Warning

The Twilio Sandbox for WhatsApp is meant for testing and discovery purposes only. It should not be used for production.


How to join a Twilio Sandbox

how-to-join-a-twilio-sandbox page anchor

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

Please note that the Sandbox expires three (3) days after joining. After this time, you should re-join to continue testing.

(information)

Info

The opt-in to one Sandbox limitation does not exist on your own Twilio number that you enable for WhatsApp.


(warning)

Warning

You cannot use custom WhatsApp notification templates with the Twilio Sandbox. Instead, the Twilio Sandbox for WhatsApp comes with three pre-configured templates for testing purposes.

To set up and use notification templates, you will need to register a Twilio Phone Number with WhatsApp.

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.


Reply to incoming messages with the Twilio Sandbox

reply-to-incoming-messages-with-the-twilio-sandbox page anchor

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:

standbox_incoming_callback_field.

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


Set a status callback URL to track message delivery

set-a-status-callback-url-to-track-message-delivery page anchor

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.

The Status Callback URL field inside the Twilio Sandbox for WhatsApp.

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


Twilio Sandbox Limitations

twilio-sandbox-limitations page anchor

Because the Twilio Sandbox for WhatsApp is made 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 are restricted to 1 message every 3 seconds.
  • Sandbox numbers are branded as Twilio numbers, i.e., with 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, please 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. Sandbox messages are billed as usual, per pricing for Twilio API for WhatsApp.(link takes you to an external page)


Now that you've been introduced 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:


Rate this page: