Skip to main content

​
E911 emergency drill mode

Fire drills for emergency dialing are standard practice on a hosted PBX. Without drill mode, a 933 dial on Orbit falls through as an unreachable destination and your dial plan, caller-ID presentation, and desk notifications have no safe end-to-end rehearsal. Drill mode closes that gap: it rewrites the dialed digits to a destination you control, so the full path executes — dial plan, coverage checks, billing, call records, webhooks — without ringing anything live.

​
What drill mode is

Drill mode is a per-organization, opt-in setting. While it is off, nothing changes: 933 is a normal unassigned code, and any custom training short code you later configure is ignored. When enabled, two dial strings are rewritten: A rewrite is rewrite-only routing: the drill destination is substituted for the dialed digits and the call proceeds through the ordinary outbound path — your trunk, the platform’s coverage and fraud checks, standard per-minute billing, a normal call record. Leave destination null and the drill lands on the platform loopback announcement server, sip:announce@drill.orbit.devotel.io — expected out-of-path behavior, dial-attempt only, no external egress.

​
Turn drill mode on and off

Both endpoints are admin-only (organization owner/admin with voice write access).

​
Read the current configuration

cURL
GET always returns 200 with the normalized record — never 404 — so your dashboard or rollout script can render the empty state directly. destination: null means the platform loopback announcement server.

​
Enable or update

cURL
  • destination accepts an E.164 PSTN number, a SIP URI, or a dialable alias (up to 200 characters). Omit it or pass null to use the platform loopback announcement server.
  • training_short_code must be 2–16 dialable characters. Setting it to 933 is rejected — the built-in test number already drills, so a duplicate code is redundant.
  • The PUT replaces only the drill record; every other voice setting on the organization is preserved.
  • Every change is recorded in your audit log.

​
Disable — and why disable clears the rest

cURL
Disabling returns the whole record to the empty state — destination and training_short_code are cleared to null in the same write. A stale destination cannot linger across an off/on cycle and silently re-arm the next time someone flips the toggle. Re-enabling always starts from a clean slate, and the API reflects that: a GET after the disable shows all three fields back at their defaults.

​
What never gets rewritten

Drill mode can never mask a live emergency call, by construction:
  • Live emergency codes are re-matched inside the drill matcher. Before any rewrite, every candidate input — the dialed string and the configured training short code — is run through the same emergency-dial matcher that blocks 911, 112, 999, and 000 on every outbound call. A candidate that resolves to a live emergency code is never rewritten. This is defence-in-depth on top of the platform-wide block described in Emergency calling, which still fires even in the impossible case a rewrite slipped past.
  • The rewrite runs after your dial plan has been translated. A dial plan entry that translates an input into a live emergency code still hits the emergency block; drill mode cannot undo that rejection.
  • The drill destination is re-examined downstream. The substituted destination passes through the same coverage, fraud, and class-of- service checks every other outbound call faces.
If an organizer configures a training short code that coincides with a live emergency code, the config is rejected at save time and declined again at drill time.

​
Failure posture: drill fails open

If the settings read trips on a transient infrastructure error, the drill check fails open: it returns “not configured” and the call proceeds unrewritten, exactly as drill mode would behave while off. A transient error can never rewrite a real destination, and it never surfaces as a call failure. Live emergency codes are unaffected — their platform block is a hard guard with no dependency on this lookup.

​
Run an end-to-end drill

  1. Enable drill mode with the PUT above. Pick a destination you can observe: your PBX’s drill announcement point, a conference bridge, an internal queue, or leave it null for the platform loopback announcement server. Optionally set the training short code your PBX dial plan already uses.
  2. Dial 933 (and the training short code, if configured) from each surface you ship: a registered desk phone, the browser softphone, an agent call flow, your PBX over the SIP trunk.
  3. Verify the full path executed. The call connects to the drill destination, the record appears in Voice → Calls with the drill destination substituted, your webhook receivers see the normal call lifecycle events, and any desk-notification or caller-ID logic you wired to emergency-style dials fires.
  4. Verify live codes still block. From the same surfaces, dial 911 or 112 and confirm the call is rejected with EMERGENCY_CALLING_NOT_SUPPORTED — drill mode must never change this. If it ever connects, disable drill mode and contact support.
  5. Disable when done. The disable write clears the destination and short code, so the next drill starts from an explicit, reviewable configuration instead of a leftover one.
Schedule the drill inside your UCaaS rollout runbook — the same window where you register the PBX and validate dial plans — and run it again after any dial plan change that touches emergency-style patterns.