Test WhatsApp messaging with the Sandbox
Testing and discovery purposes only
Use the Twilio Sandbox for WhatsApp for testing and discovery purposes only. Don't use it in a production environment.
Twilio Console trial accounts
Twilio Console trial accounts use Try out WhatsApp to activate a WhatsApp testing environment and connect a device. Legacy Console trial accounts and upgraded accounts use the Sandbox setup steps on this page.
The Twilio Sandbox for WhatsApp is a pre-configured environment in the Twilio Console for testing the following functionality:
- Sending business-initiated messages
- Replying to user-initiated messages
- Configuring a webhook URL and a status callback URL
You don't need a WhatsApp Business Account or a registered WhatsApp sender to use the Sandbox.
Twilio provides the Sandbox with a shared phone number (+14155238886). While all Sandbox users use the same number, only users who have joined your specific Sandbox can receive messages from you.
Watch the following video to learn how to use the Sandbox to send and receive WhatsApp messages.
- You can only message end users who have joined your Sandbox. Messaging other users will fail with Error 63015.
- The Sandbox supports functional testing, but not load testing of profile traffic.
- The Sandbox number is a Twilio number and displays the Twilio logo.
- The Sandbox number can only send one message every three seconds.
- For business-initiated messages from the Sandbox, you can use only pre-approved templates.
- The Sandbox session expires three days after joining. After this, end users need to rejoin the Sandbox.
- The Sandbox number might be temporarily restricted from sending to certain countries, such as Brazil or Indonesia, which can cause message failures. If this happens, contact Twilio Support. To ensure more reliable delivery to recipients in other countries, register your own sender with its primary business location and the correct sender country code in each destination country. For setup instructions, see WhatsApp Self Sign-up (direct customers) and WhatsApp Tech Provider Program (Independent Software Vendors (ISVs)).
You can send unlimited messages and use the Twilio Sandbox for WhatsApp for as long as you need. However, Twilio free trial accounts include 100 WhatsApp messages as part of their trial free units. Sandbox messages are billed at standard Twilio API for WhatsApp pricing.
Twilio Console trial accounts use Try out WhatsApp to activate a WhatsApp testing environment and connect a device.
- Sign up for Twilio.
- From the Twilio Console, open Messaging. In Popular channels, find WhatsApp and click Try out WhatsApp.
- If prompted, acknowledge the Sandbox terms and click Continue.
- Scan the QR code with WhatsApp, or send the prepopulated join message from your device to the number provided.
Multiple end users can join the same Sandbox, but each must send the join <your sandbox code> message to the Sandbox number to join.
When a user sends your business a message, it opens a 24-hour customer service window. During this window, you can send free-form text and media without a message template. Outside the window, you can only message users with an approved template. Learn more about customer service windows and message templates.
Info
Sending join <your sandbox code> to the Sandbox number starts a customer service window.
The Twilio Sandbox for WhatsApp comes with the following pre-approved templates for testing purposes:
- 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}}"
Note: The double-bracketed numbers are placeholders for your custom values. In your code, provide these values as key-value pairs. For example, if you use the Appointment Reminders template, {"1":"2025/7/15","2":"3:00p.m."} will show "Your appointment is coming up on 2025/7/15 at 3:00p.m.".
You can't use custom message templates with the Sandbox. To set up and use custom message templates, you need to register a WhatsApp sender through WhatsApp Self Sign-up (direct customers) or WhatsApp Tech Provider Program (Independent Software Vendors (ISVs)).
You can use the Sandbox to explore replying to incoming WhatsApp messages.
When an end user sends you a WhatsApp message, you can reply to that message within the 24-hour customer service window. During the 24-hour window, you can reply with free-form messages.
When an end user sends a WhatsApp message, Twilio sends a webhook to your webhook URL. Typically, the webhook URL points to your application. When Twilio receives a message, it makes a request to your URL. You can reply using TwiML, Twilio's markup language for message instructions. Learn more about how to reply with TwiML in the language of your choice.
In the Sandbox, you can set the webhook URL in the When a Message Comes in field under Sandbox settings > Sandbox configuration.
You can receive real-time status updates for WhatsApp messages that you send and receive with the Sandbox.
When you set a status callback URL, you can receive requests from Twilio with information about the delivery status of your WhatsApp message. Twilio sends a request to your status callback URL each time your message status changes to one of the following: queued, failed, sent, delivered, or read. Learn more about tracking the message status of outbound messages.
In the Sandbox, you can set the status callback URL in the Status callback URL field under Sandbox settings > Sandbox configuration.
- Get started with the WhatsApp for Twilio quickstart.
- Learn about using WhatsApp Business Accounts with Twilio.
- Register your WhatsApp sender with WhatsApp Self Sign-up (direct customers) or WhatsApp Tech Provider Program (ISVs).
- Learn about WhatsApp messaging best practices.