To test the WhatsApp API before registering a number, request a sandbox API key over WhatsApp, connect an HTTPS webhook, and send messages and templates to your own phone. The sandbox is free and available immediately.[9] A developer can start building the integration the same day, with no business number, account approval, or sales call. Every test runs on the developer’s own phone and stays away from real customers. When the business is ready to go live, the tested code moves over with a new server address, API key, and webhook.
Key Takeaways
- A sandbox API key arrives as a WhatsApp reply to one START message, with no registered number or sales call needed.
- Each sandbox key covers up to 200 messages, rejected requests included, all sent to one fixed recipient: the tester’s own WhatsApp.
- The sandbox checks the code’s authentication, incoming webhook events, and the shape of message and template requests.
- Tests that need standard business number rules belong on a Meta-provided 555 number, which is billed at standard rates like any regular number.
- 360Dialog, an Official Meta Solution Partner, provides the sandbox and the production WhatsApp Business API access.
What Is the WhatsApp API Sandbox?
The WhatsApp API sandbox is a 360Dialog test environment that sends freeform messages and templates to one fixed recipient: the tester’s own WhatsApp account.[1] A developer uses it to prove the code path: the auth header, the webhook, and the payload shape. Each test account gets its own API key, tied to that one recipient.
That recipient is the tester’s phone number, even a landline that runs WhatsApp. When the tester does not share the number, the recipient is a “Business-Scoped User ID” (BSUID). On the test phone, the tester plays the customer, sending messages to the sandbox and receiving the replies.
How Do You Get a Sandbox API Key?
Send the word START from WhatsApp to the 360Dialog sandbox number, and the sandbox API key comes back as a reply. One message from the test phone is the whole request. Every sandbox API call then carries that key in its header.
The sandbox number is on the Sandbox page of our documentation, along with a click-to-chat link and a QR code. START must be in capitals. WhatsApp may ask the tester to share contact info. If the tester declines or answers late, the key still arrives within 5 minutes, along with a BSUID.
That account has no phone number attached. Every request from it carries the BSUID in the recipient field and leaves out to. Checking which identifier the key uses saves a round of HTTP 403 errors.
How Do You Set Up the Sandbox Webhook?
The sandbox webhook is the HTTPS address where the code receives the tester’s incoming messages and a status update for each message the API sends. One API call registers it. With the webhook set first, every later test shows up as an event the code can parse.
Register the address on the sandbox host with the key in the header:
curl -X POST https://waba-sandbox.360dialog.io/v1/configs/webhook \
-H 'Content-Type: application/json' \
-H 'D360-API-KEY: <YOUR_API_KEY>' \
-d '{"url": "<YOUR_HTTPS_WEBHOOK_URL>"}'A successful call returns HTTP 200 with the URL. A plain http address fails with HTTP 400 and the message “url must be HTTPS”. For quick tests, webhook.site and RequestBin hand out temporary HTTPS addresses, and ngrok tunnels a local port. The same call swaps in a new webhook address at any time.
To confirm the hook works, message the sandbox number again from the test phone. An inbound event arrives under entry[].changes[].value, and sent, delivered, and read statuses follow each outbound message. Phone number accounts receive wa_id, from, and recipient_id. BSUID accounts receive user_id, from_user_id, and recipient_user_id in their place.
How Do You Send Your First Message and Template?
Send a short text through the API to the tester’s own WhatsApp, then send a template through the same call. A delivered text and template confirm that authentication, request format, and status events work end to end.
The text goes to /v1/messages on the sandbox host with the same two headers:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<YOUR_PHONE_NUMBER>",
"type": "text",
"text": { "body": "Hello from the sandbox" }
}Every request needs the messaging_product field. The to value must exactly match the number the key is tied to, and BSUID accounts send "recipient": "<YOUR_BUSINESS_SCOPED_USER_ID>" in its place. Any other value, or neither field, returns HTTP 403. A valid request returns HTTP 201 with a message ID.
The sandbox offers three fixed templates:
| Template | What it lets you test |
|---|---|
disclaimer | A fixed text message with no parameters and an empty components array |
first_welcome_messsage | A body parameter that personalizes the receiver’s name |
interactive_template_sandbox | A template with two buttons |
A template request sets "type": "template", the template’s name, and the language code en.
What Can’t You Do in the Sandbox?
The sandbox can’t message anyone except its fixed recipient, send templates outside its set of three, upload or retrieve media by media ID, or go past 200 messages. Knowing these limits up front shows which tests belong on a registered number.
Each request that gets through to the messaging API uses one of the 200, even when the message is rejected. Once all 200 are used, the sandbox returns HTTP 429. Checking payloads before each send keeps the budget for real tests.
A live number handles each limit differently:
| Sandbox limit | On a live number |
|---|---|
| One fixed recipient | Customers: freeform messages inside an open customer service window, templates outside it[2] |
| Three predefined templates | The business’s own templates, each approved before use (why templates get rejected) |
| No media by media ID | Upload, retrieval, and deletion by media ID, with files stored for 30 days after last use[3] |
| 200 messages | Meta’s messaging limits for the number |
Sandbox or Meta-Provided 555 Number: Which Should You Use?
The sandbox fits a first check of code against the API, and a Meta-provided 555 number fits tests that need a standard business number on the WhatsApp Business Platform. The choice decides what the test proves and what has to be rebuilt later.
| Question | Sandbox | Meta-provided 555 number |
|---|---|---|
| What it proves | Auth, webhook handling, and payload shape | Behavior under standard business number rules |
| Who issues it | 360Dialog | Meta, which also manages it |
| Best for | Code checks | Onboarding, evaluation, integration tests, demos, and internal QA |
| Where it can go | Stays tied to one test recipient | Cannot move to another WhatsApp account or leave the WhatsApp Business Platform |
Eligible businesses can get up to two 555 numbers from Meta during Embedded Signup, each with the US country code +1 and the 555 area code.[4] A 555 number is verified automatically and follows standard pricing rules and quality ratings. Its display name still needs approval before the first message. We bill each one at standard rates, like a regular number, and do not refund 555 numbers onboarded by mistake.[5] Live customer traffic belongs on a regular number, because a 555 number’s setup and history cannot move to a new one.
What Changes When You Move From the Sandbox to a Live Number?
Moving to a live number changes the server address, the API key, and the webhook. The authentication header stays the same. Planning these changes before the switch keeps the sandbox code reusable.
A live number needs an approved WhatsApp Business account (WABA), a registered phone number, an API key, and an HTTPS webhook. Meta is splitting the WABA into a WhatsApp account, which holds the phone number, and a Messaging account, which holds templates, billing, and webhook subscriptions.[6] Meta registers numbers onboarded through Embedded Signup for the WhatsApp Cloud API only. Three things change in code and config:
- Host and path: Messages go to
https://waba-v2.360dialog.io/messages, which drops the sandbox path’s/v1prefix. TheD360-API-KEYheader stays. - API key: Each phone number gets its own key in the 360Dialog Hub.[7] Save the key when it appears, because the Hub shows it only once. Creating a new key revokes every earlier one. For partner clients, the integration partner creates the key.
- Webhook: Replace the temporary webhook.site, RequestBin, or ngrok address with a stable HTTPS endpoint that has a valid SSL certificate. Its domain needs no underscores and no explicit ports.[8] Size the endpoint for status callbacks, which add about three times the outbound volume on top of inbound traffic. Meta retries failed deliveries for up to 7 days.
A sandbox run settles authentication, webhooks, and payloads before any number, template review, or customer is involved. The team then spends its first days on a live number on the conversations themselves.
Production WhatsApp Business API access from 360Dialog, an Official Meta Solution Partner, uses the same D360-API-KEY header as the sandbox. Get API access to register a number and point the tested code at the production host.
Frequently Asked Questions
Why Is the WhatsApp Sandbox Not Sending My Message?
A sandbox message fails when the key, the recipient, or the message budget does not match what the sandbox expects. HTTP 401 means the D360-API-KEY header is missing or invalid. A 403 response means the to or recipient value differs from the one the key is tied to, or the body has neither. Once the 200-message limit is used up, the sandbox returns HTTP 429.
HTTP 502 and HTTP 504 mean the message did not reach the messaging API in time. Retry the request later.
Can the WhatsApp Sandbox Send Messages to More Than One Number?
No, the WhatsApp sandbox sends only to the one recipient its API key is tied to: the tester’s phone number or business-scoped user ID. Any other value in the request returns HTTP 403. Testing with a colleague’s phone, a QA device, or a group of users needs a number on the WhatsApp Business Platform, such as a registered business number or a Meta-provided 555 number.
Can You Use Your Own Templates in the WhatsApp Sandbox?
No, the WhatsApp sandbox sends only its three predefined templates: disclaimer, first_welcome_messsage, and interactive_template_sandbox. Templates cannot be created or edited there. Testing a business’s own template copy, buttons, or media headers needs a live number, where each template is approved before its first send.
What Is a Business-Scoped User ID in the WhatsApp Sandbox?
A business-scoped user ID (BSUID) is the ID WhatsApp uses for a person within one specific business when that person’s phone number is not shared. In the sandbox, a key issued without a shared number is tied to a BSUID. Every request from that account names the BSUID in the recipient field, and webhook events identify the tester by it.
Does the WhatsApp Sandbox Support Media Messages?
The WhatsApp sandbox does not support uploading or retrieving media files by media ID. Image, video, and document tests that rely on uploaded media need a live number. There, the production API uploads, retrieves, and deletes media by media ID, and uploaded files stay stored for 30 days after their last use.
Sources
[1] 360Dialog Docs, “Sandbox,” https://docs.360dialog.com/docs/get-started/sandbox (accessed October 29, 2026).
[2] 360Dialog Docs, “Send and Receive Messages,” https://docs.360dialog.com/docs/guides/send-and-receive-messages (accessed October 29, 2026).
[3] 360Dialog Docs, “Upload, Retrieve or Delete Media,” https://docs.360dialog.com/docs/messaging/media/upload-retrieve-or-delete-media (accessed October 29, 2026).
[4] Meta for Developers, “Embedded Signup,” section “555 business phone numbers,” https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/overview#555-business-phone-numbers (updated October 27, 2026; accessed October 29, 2026).
[5] 360Dialog Docs, “Meta Provided (555) Phone Numbers,” https://docs.360dialog.com/docs/resources/phone-numbers/meta-provided-555-phone-numbers (accessed October 29, 2026).
[6] Meta for Developers, “Updates to WhatsApp Business accounts,” https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/ (updated September 22, 2026; accessed October 29, 2026).
[7] 360Dialog Docs, “API Key,” https://docs.360dialog.com/docs/hub/api-key (accessed October 29, 2026).
[8] 360Dialog Docs, “Webhook,” https://docs.360dialog.com/docs/messaging/webhook (accessed October 29, 2026).
[9] 360Dialog Docs, “Overview,” https://docs.360dialog.com/docs (accessed October 29, 2026).
