Sandbox Magic Numbers Playbook

The sandbox inventory that drives simulated traffic is spread across the sandbox test mode walkthrough, the connect your first channel tutorial, the first SMS end-to-end recipe, and the sandbox API cookbook. This playbook sandwiches the whole inventory into one recipe: the magic-number chart, failure-mode rehearsal, inbound injection, and the checklist that takes you from a test key to a live key. Run it as a single script before you go live.

1. The big picture — a key that simulates without callers

Orbit sandbox activates on a dv_test_sk_ API key (or a sandbox organization, or the X-Test-Mode: true dashboard header). With that signal, every send short-circuits before a provider is resolved: no carrier is touched, no balance moves (cost_usd_cents: 0), and the recipient’s trailing digit decides the simulated outcome. Nothing about your request shape changes — you graduate by swapping the key, not the code. The three activation signals are listed on the sandbox overview. Public-form sandbox keys (dv_test_pk_) reach sandbox endpoints only and can be embedded in client-side test apps; rotation preserves the form, so a public key never flips into a secret one.

2. The magic test numbers chart

Send to any E.164 recipient and the trailing digit selects the delivery scenario. Each scenario replays the same intermediate → terminal sequence a real carrier produces, delivered as message.status webhooks to your sandbox webhook URL:

Trailing digit	Terminal status	What it exercises	Webhook sequence
`1`	never (ACK only)	DLR-timeout / dead-letter handling	`sent` only, `fires_dlr: false`
`2`	`delivered`	Happy path (~50 ms terminal)	`sent` → `delivered`
`3`	`undelivered`	Handset reject (~1 s)	`sent` → `undelivered`
`4`	`failed`	Pre-submit network failure (~100 ms, no `sent` ACK)	`failed`
`5`	`expired`	TTL exceeded (3 s)	`sent` → `expired`
`6`	`unknown`	Carrier never reports (5 s)	`sent` → `unknown`
`7`	`rejected`	Carrier spam filter (~150 ms)	`rejected`
`8`	`blocked`	Suppression / opt-out (~50 ms)	`blocked`
`9`	`delayed` → `delivered`	60 s lag, eventually delivered	`sent` → `delivered`
`0`	`delivered` (carrier rewrite)	Regulatory footer appended	`sent` → `delivered` with `body_rewritten_by_carrier: true`

Every webhook carries state_class (intermediate / terminal) and is_terminal, matching the tags production stamps. The same catalog is machine-readable from GET /api/v1/sandbox/numbers; the full semantics stay canonical at magic numbers.

WhatsApp window-status injection

The same trailing-digit convention drives WhatsApp sends in the sandbox. For the reply side, inject a synthetic inbound with channel: "whatsapp" — the recipient “replies,” Orbit opens the 24-hour customer-service window, and a follow-up free-form send then goes through. Check the state your composer checks: GET /api/v1/messages/whatsapp/window-status. That pair — inbound injection to open the window, then a free-form send — is the whole template-window rehearsal, with no Meta account involved. The sandbox gives you a full WhatsApp loop — template send, simulated receipt, injected reply, free-form follow-up — before you run Meta’s embedded signup in production.

Mint a sandbox key with mode Test under Settings → API Keys (dv_test_sk_).
Bulk-provision a deterministic fictional number from the reserved +1 555 01XX range:

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/provision-numbers \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 2 }'

Send a WhatsApp message from one provisioned number to a magic recipient — the trailing digit picks the receipt:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "from": "+15550100",
    "type": "template",
    "template": {
      "name": "sandbox_check",
      "language": { "code": "en" },
      "components": []
    }
  }'

Inject the synthetic reply (below), then send a free-form type: "text" follow-up inside the window the injection opened.

When the same code goes to production, the connect-your-first-channel Recipe B walkthrough covers the real Meta signup, template approval, and the live window-status probe.

4. Perfecting the failure modes in the simulator

Rehearse the states your production handlers must survive. Aim each one at the magic number whose trailing digit emits exactly that state:

Terminal status	Trigger recipient	Handler branch to verify
`failed`	`+15005550004` (digit `4`)	Pre-submit retry — arrives with no `sent` ACK, so the branch must not assume an intermediate update fired
`undelivered`	`+15005550003` (digit `3`)	Handset reject arrives ~1 s after `sent` — test the code that distinguishes “accepted, then failed” from a pre-submit failure
`rejected`	`+15005550007` (digit `7`)	Policy/spam reject — verify your retry logic backs off on policy errors instead of retrying immediately
`expired`	`+15005550005` (digit `5`)	TTL expiry — confirm your DAG accepts `expired` after `sent` and your alerting does not page on the 3 s delay

Sandbox receipts never mutate stored message state — the stored message keeps its test_sent status, and the receipts exist only on the webhook stream. Your failure branch reads the same payload shape it would in production.

5. Pre-conditioning inbound replies

Drive the receive side by pushing synthetic replies into your agent queue and inbox — no forged provider webhook, no handset:

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",
    "contact_name": "QA Handset"
  }'

The injection lands exactly like a real inbound webhook: contact, conversation, and message rows are created, the unassigned-conversation notification fires, and your agent’s queue view refreshes. channel accepts sms, mms, or whatsapp; a repeated sender threads into the open conversation (created_conversation: false). Use it to rehearse auto-responders, STOP-keyword handling, inbox routing, and the 24-hour WhatsApp window from section 2. Endpoint bounds and error shapes are in the cookbook.

6. Graduating production — test key to live key

The go-live checklist handles the cut; this is what remains intact and what changes:

Run the shared five-step gate — GET /api/v1/sandbox/pre-launch-checklist — until readyForLaunch: true. It is callably with either key and always evaluates your live workspace, so CI and the dashboard agree. Each item is covered on the pre-launch checklist page.
Complete KYC and fund the balance — together they switch on live sending.
Mint a live key (dv_live_sk_) under Settings → API Keys and swap it in. The request bodies stay identical; the sandbox signal rides on the key, not the code.
Walk the human sign-off on the go-live checklist for numbers, webhooks, guardrails, and compliance.

Two pitfalls stay intact by design: magic recipients in live mode hit the real carrier (the trailing-digit convention is sandbox-only), and provisioned provider: "sandbox" numbers belong to the sandbox workspace only — re-register live numbers before cutting traffic. Both the sandbox test-mode guide and the cookbook repeat these rules; this playbook keeps them with the inventory they affect.

Sandbox and test mode — the end-to-end walkthrough this playbook sandwiches
Sandbox API cookbook — request/response pairs for every route exercised here
Sandbox dashboard walkthrough — the console equivalent
Magic numbers reference — canonical digit-to-scenario semantics
Pre-launch checklist — the five-step gate, item by item
Connect your first channel — production WhatsApp signup (Recipe B) after the sandbox rehearsal

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Sandbox magic numbers playbook: one recipe for every simulated outcome

Sandbox Magic Numbers Playbook

1. The big picture — a key that simulates without callers

2. The magic test numbers chart

WhatsApp window-status injection

4. Perfecting the failure modes in the simulator

5. Pre-conditioning inbound replies

6. Graduating production — test key to live key

​Sandbox Magic Numbers Playbook

​1. The big picture — a key that simulates without callers

​2. The magic test numbers chart

​WhatsApp window-status injection

​3. Recipe: connect WhatsApp inside the sandbox without Meta signup

​4. Perfecting the failure modes in the simulator

​5. Pre-conditioning inbound replies

​6. Graduating production — test key to live key

​Related pages

Sandbox Magic Numbers Playbook

1. The big picture — a key that simulates without callers

2. The magic test numbers chart

WhatsApp window-status injection

3. Recipe: connect WhatsApp inside the sandbox without Meta signup

4. Perfecting the failure modes in the simulator

5. Pre-conditioning inbound replies

6. Graduating production — test key to live key

Related pages