Sandbox and Test Mode

Orbit sandbox is a complete simulation environment. Your integration code runs unchanged against the real API — the same endpoints, the same request shapes, the same webhook format — and Orbit short-circuits every send, purchase, and verify call before it touches a carrier. Nothing bills, no real phone rings, no audit rows you need to clean up later. Sandbox mode activates when your request uses any of:

A sandbox API key (prefix dv_test_sk_), or
An organisation flagged is_sandbox, or
The X-Test-Mode: true header on a dashboard session.

Everything below is keyed off that signal. When you flip to a live key (dv_live_sk_), the same request bodies hit production paths.

Simulate sends and receipts with magic numbers

POST to the Messages API aiming at a magic test number, and Orbit returns a deterministic delivery receipt (DLR). The trailing digit of the recipient picks the scenario — 2 delivered, 3 undelivered, 7 rejected — so you can drive every retry, dead-letter, and alerting branch you have.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "from": "+15550100",
    "body": "delivered scenario"
  }'

The receipt sequence arrives as message.status webhooks to your sandbox webhook URL, tagged sandbox: true. The full digit-to-scenario table lives at Sandbox magic numbers.

Buy test numbers without touching a carrier

POST /api/v1/numbers/purchase with a sandbox credential returns a deterministic fictional number from the reserved +1 555 01XX range. There is no provider call, no wallet charge, and the number is marked provider: "sandbox" in your tenant inventory.

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15550100",
    "country_code": "US"
  }'

Response:

{
  "data": {
    "id": "num_…",
    "phone_number": "+15550100",
    "status": "active",
    "provider": "sandbox",
    "monthly_cost": "0.0000"
  }
}

Use these sandbox-only numbers as the from in your send tests; the trailing-digit table then drives the recipient-side outcome.

Inject a simulated inbound message

To test the receive side — auto-responders, STOP keywords, inbox routing — you don’t need to hand-forge a provider webhook. POST a synthetic inbound (mobile-originated) message into your sandbox inbox:

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/inbound \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15005550002",
    "channel": "sms",
    "body": "STOP"
  }'

The message lands in your sandbox inbox like a real reply: the contact, conversation, and message rows are created, the unassigned-conversation notification fires, and your inbox view refreshes. This endpoint refuses any request that is not in sandbox mode with 403 SANDBOX_ONLY, so a live inbox can never be polluted with synthetic traffic.

Deterministic verification codes

The Verify API honours custom_code only on sandbox credentials, so your QA and CI flows can assert a fixed OTP end to end without parsing a real message.

curl -X POST https://api.orbit.devotel.io/api/v1/verify/send \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "channel": "sms",
    "custom_code": "123456"
  }'

Then check it:

curl -X POST https://api.orbit.devotel.io/api/v1/verify/check \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "code": "123456"
  }'

In live mode custom_code returns 403 CUSTOM_CODE_FORBIDDEN — pinning the OTP is a sandbox privilege, never a production one. A live verify send still generates a random code server-side.

Reset and re-seed the sandbox

When a test run leaves debris, reset the whole sandbox workspace or seed deterministic fixtures:

Endpoint	Effect
`POST /api/v1/sandbox/reset`	Wipes contacts, conversations, and messages; releases sandbox numbers
`POST /api/v1/sandbox/provision-numbers`	Bulk-provisions deterministic `+1 555 01XX` numbers
`POST /api/v1/sandbox/spawn-fixture-contacts`	Creates fixture contacts (optionally with conversations)

All three reject non-sandbox requests with 403 SANDBOX_ONLY before a single row changes.

Pre-launch gate

Before go-live, Orbit evaluates a shared checklist against your org — callable from either the live or the sandbox context, with the same result either way:

curl https://api.orbit.devotel.io/api/v1/sandbox/pre-launch-checklist \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

{
  "data": {
    "readyForLaunch": false,
    "items": [
      { "id": "sandbox_workspace_ready", "status": "complete" },
      { "id": "live_workspace_ready", "status": "pending" },
      { "id": "sandbox_token_minted", "status": "complete" },
      { "id": "integration_exercised", "status": "complete" },
      { "id": "ip_allowlist_configured", "status": "pending" }
    ]
  }
}

readyForLaunch flips to true when every item is complete. Wire it into your launch script to fail CI on an unfinished gate, then walk the human sign-off in the production go-live checklist.

Graduating to production

Finish the pre-launch checklist.
Complete KYC and fund your balance — these two unlock live sending.
Mint a live key (dv_live_sk_) under Settings → API Keys.
Walk the production go-live checklist for numbers, webhooks, guardrails, and compliance.

Your code needs no changes — the sandbox signal comes from the key, not from request bodies.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Sandbox and test mode: build end to end without carrier spend

Sandbox and Test Mode

Simulate sends and receipts with magic numbers

Buy test numbers without touching a carrier

Inject a simulated inbound message

Deterministic verification codes

Reset and re-seed the sandbox

Pre-launch gate

Graduating to production

​Sandbox and Test Mode

​Simulate sends and receipts with magic numbers

​Buy test numbers without touching a carrier

​Inject a simulated inbound message

​Deterministic verification codes

​Reset and re-seed the sandbox

​Pre-launch gate

​Graduating to production

Sandbox and Test Mode

Simulate sends and receipts with magic numbers

Buy test numbers without touching a carrier

Inject a simulated inbound message

Deterministic verification codes

Reset and re-seed the sandbox

Pre-launch gate

Graduating to production