The sandbox
Every team has a sandbox from the day it signs up. A call with a sandbox key behaves like a live one, but nothing reaches a real phone and nothing is charged.
You need a sandbox key. See API keys and base URLs.
What's different from live
| Sandbox | Live | |
|---|---|---|
| Base URL | https://sandbox-api.ponitor.com | https://api.ponitor.com |
| SMS | Simulated networks, with delivery reports a few seconds later | Orange and Lonestar Cell MTN |
| Your team's sandbox WhatsApp number | Your own WhatsApp numbers | |
| Airtime and data | A simulated provider that answers at once | Real top-ups |
| USSD | *123#, dialled from the Simulator | Your own codes, dialled from real phones |
| Webhooks | Sent as in live | Sent |
| Money | A test balance | Your account balance |
The sandbox keeps its own data. A message, session, contact or balance there never shows in live, and the other way round.
Mobile Money payments, push-pull and workspaces aren't in the sandbox, because they move real money. Nor is connecting your own WhatsApp number. A payments call with a sandbox key returns 409 Conflict.
What's ready for you
You don't request anything in the sandbox. Every team has these from its first visit to Test mode:
| In the sandbox | |
|---|---|
| Sender ID | PSandbox, shared by every team. It only sends. |
| Short Code | 1234, a two-way Short Code shared by every team. |
| USSD code | *123#. Set its webhook under USSD › Codes. |
| SMS templates | A few samples to start from. |
| WhatsApp templates | A few samples, already approved. |
| Contacts | Simulator Phone (231880000100), Test Fails (231770000001) and Test Pending (231770000002), in the group Sandbox Testers. Send a campaign or a bulk top-up to the group to see a success, a failure and a pending result at once. |
PSandbox and 1234 are the only SMS senders in the sandbox:
- A Sender ID or Short Code request made in the sandbox returns
409 Conflict. - A send from any other SMS sender, such as your live Sender ID, returns
400and says it's a live sender.
Other teams can't see what you send from PSandbox or 1234, and a reply to 1234 reaches only the team it's for.
The Simulator
Simulator, in the app's menu in Test mode, is a pretend phone for your sandbox. Its number starts as 0880 000 100. Change it to any Liberian mobile number, and use it as the recipient in your sandbox calls.
| App | What it does |
|---|---|
| Messages | SMS your sandbox sends to this number arrive here, from PSandbox or 1234, each with its status. Text 1234 back, and the reply reaches your Inbox and your team webhook, as a message.received event. |
| The same, with your sandbox WhatsApp number. | |
| Phone | Dial *123# on the keypad. Each step goes to your USSD webhook, with the phone's number as the caller's. |
Test failures with magic numbers
The last four digits of the recipient decide what happens to a message or a top-up:
| Recipient ends in | What happens |
|---|---|
0001 | It fails, as if the network or provider refused it. An SMS ends as UNDELIVERED. |
0002 | No delivery report or top-up result ever comes. An SMS or WhatsApp message stays SENT, and becomes UNKNOWN after 48 hours, as in live. A top-up stays PENDING. |
| Anything else | It succeeds. |
For example, send to +231770000001 to see how your code handles a message that isn't delivered.
The test balance
Your sandbox starts with a $1,000 test balance. Each call costs what it would in live, so the cost in responses and the figures in reports are real. When the balance drops under $100, it tops itself back up to $1,000.
To test running out of money:
- In Test mode, open Billing.
- Choose Set Test Balance. Enter $0, untick Refill Automatically, and save.
Your next send fails with the same insufficient-balance error as in live. To refill, open Set Test Balance again and tick Refill Automatically. The balance goes back to $1,000.
Test data is kept 30 days
Each night the sandbox deletes test data older than 30 days: messages, empty conversations, USSD sessions, top-ups and test-balance history. These stay: your keys, PSandbox and 1234, your USSD code and its webhook, templates, contacts, groups, webhooks and the test balance.
Next steps
- When your integration works, see Going live.
- For the sandbox's request limits, see Rate limits.