Get started with the Twilio Sandbox for WhatsApp
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.
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
The Twilio Sandbox for WhatsApp is meant for testing and discovery purposes only. It should not be used for production.
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.
Info
The opt-in to one Sandbox limitation does not exist on your own Twilio number that you enable for WhatsApp.
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.
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:
queued, failed, sent, delivered, read.