555 test numbers

Every account can call and text numbers in area code 555, +1 555 XXX XXXX, with nothing to set up. These calls and texts never reach a phone company. A test call is answered by Phone Lab, which behaves the way the last four digits say. A test text gets an automatic reply from the number you texted. Both are free.

Use them to build and demo a dialer, an inbox or a texting flow before you connect a carrier, register a brand or add funds.

Only area code 555 counts. The sample numbers in these docs, such as +13125550142, have a real area code and are real numbers. They're dialed and billed like any other number.

Which 555 numbers to use

You can save a test number on a contact, through the Contacts API, the dashboard or an import, and then call or text that contact like any other.

These aren't the same as the test numbers on the Dialing rules page. Those are your own real phones, which a retail account can reach while support has it in testing mode. See Test on retail, then go live on BYOC.

Test calls

Call a 555 number from the dashboard dial pad or from a Building Blocks dialer. You don't need a caller ID of your own. The last four digits pick what happens, so any 555 number ending in 0005 is busy:

Use 0002 and 0003 to test answering-machine detection, and 0008 to 0010 to test keypad menus, such as confirm, opt out and transfer to an agent.

Five test calls at a time

An account can have five test calls in progress at once. A sixth is refused with reason sandbox_concurrency. The caller hears that five test calls are already in progress, and the call ends. Hang up one of the others and call again.

Test texts

Text a 555 number the way you text anyone: with POST /sms, Send a reply, a Building Blocks widget, the dashboard, a campaign or an automation.

curl -X POST https://api-v2.dropcowboy.com/sms \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Idempotency-Key: 4c8e2a6f-1b3d-4f7a-9e5c-2d6b8f1a3c97" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15555550123",
    "body": "Your order is ready for pickup."
  }'

A few seconds later, the 555 number replies:

sandbox got your message: Your order is ready for pickup.

The reply is an ordinary inbound text. It lands in the conversation with that contact and arrives on contact.msg.received; see Inbound messages. Your send's own result arrives on contact.sms.status and your callback_url, like any other text.

You don't need a phone number to text a 555 number. If you send from a phone_line_id, or from a number your account owns, we use it. Otherwise we pick a 555 sender for your account, and the reply comes back to it. A 555 sender can only text 555 numbers.

Replies that stop

So that an auto-responder or an AI agent can't loop forever, a 555 number doesn't reply to:

• A text that starts with sandbox got your message:.
• More than 10 texts in an hour from the same sender. Later texts still send, but get no reply until the hour has passed.

What test texts skip

A test text goes out without the checks a real text needs. That covers calling hours, the do-not-contact list, known litigators, consent, brand and texting campaign registration, identity verification and the contact frequency limit. When one request covers several numbers, only the 555 numbers skip them. Every real number is still checked.

RCS isn't simulated. A template_id sent to a 555 number fails with 400 and code sandbox_rcs_unsupported, so send body instead. In a campaign, the template's fallback text goes out.

Cost

Test calls and test texts, including the replies, are free. They don't touch your balance or your plan allotment, and they don't count toward a spending limit.

Building Blocks without a carrier

An account with no connected carrier, or no funds, can still mint a dialer:webrtc or phone:hub site token. The token is limited to 555 numbers, and the mint response says so:

{
  "data": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20vIiwic3ViIjoiYWdlbnQtNDIifQ.c2lnbmF0dXJl",
    "expires_at": 1774042500000,
    "jti": "7b3e9f1d-5c2a-4e8b-a6d4-1f9c3e7b5a28",
    "sandbox_only": true,
    "sandbox_only_reason": "byoc_required"
  },
  "meta": { "request_id": "2e6a9c4f-8b1d-4f3e-a7c5-9d2b6e1f4a83" }
}

Check Building Blocks readiness returns the same two fields, so you can tell before you mint.

A call or text to a real number with a sandbox-only token fails with 403 and code sandbox_only. A call dialed from the dialer widget is refused with the same reason: the caller hears that the connection can only call 555 numbers, and the call ends. Connect a carrier and add funds, then mint a new token. A token minted before that stays sandbox-only until it expires.

Common problems

• A call or text failed with sandbox_only. The site token is limited to 555 numbers. Connect a carrier and add funds, then mint a new token.
• A test call was refused with sandbox_concurrency. Five test calls are already in progress. Hang one up and call again.
• A test text got no reply. It started with sandbox got your message:, or the same sender has had 10 replies in the last hour. Wait, then send again.
• A text to a number like +13125550142 was charged or checked. That's a real number with a real area code. Only area code 555 is a test number.
• A 555 number returned a result code but never replied. It's in a reserved range. Use a number outside +1 555 000 to +1 555 003.

For more symptoms and fixes, see Troubleshooting. Every code is in Outcomes.