Skip to main content

​
On-call escalation stack: which guide to open first

Devotel Orbit’s on-call surface is three guides that each own one sub-task. None of them duplicates the others, but nothing helps until you open the right one. This page is the router: it picks the guide for the ask, then walks one rotation end-to-end across all three, with the payload each step actually sends.

​
Pick the right guide

The supervisor-ladder handoff is in the runbook: a step whose target is a users list (named responders and supervisors) rather than a live rotation. Four-eye-style approvals are a different lane — see the two-officer approvals guide — but the “page the supervisor on shift” step belongs in your escalation policy, and the runbook is where that policy tuning lives.

​
The worked rotation, end to end

Walk one rotation from nothing to rehearsed. Each step names the guide that owns it and shows the payload you’d actually send, so you can tell in one read which page has the depth you need.

​
Step 1 — alerting: define the rotation and resolve it

A rotation is an anchor (the ISO instant the first member’s shift begins), a cadence, and an ordered members list. Send it to resolve to confirm who holds the pager now and who is next:
The response names the current holder, the exact shift window, and the next hand-off — read these four fields on every call:
on_call is your trigger: the ordered roster an escalation policy points at. Pass an optional at to resolve a past or future instant — the alerting guide covers the anchor math and the member-string contract in full.

​
Step 2 — escalation runbook: chain the policy and preview the timeline

The policy chains the ladder: the rotation over push/sms on the early step, a users fallback (your supervisor) over voice on the late step, an explicit escalate_after_seconds window per step, and a repeat counter that loops the whole policy if nobody ever acknowledges:
Post it to POST /api/v1/oncall/escalation/plan and read the flattened timeline back before an incident depends on it. Each page row carries its round, step, offset_seconds from incident start, the concrete fire_at instant, and the resolved targets and channels: Two steps with repeat: 1 is four pages, twenty-five minutes from first page to exhaustion. The runbook walks the offset arithmetic, the re-resolve-at-fire-instant rule, and the tuning bands for the step windows.

​
Step 3 — the drill: rehearse the lifecycle in the dashboard hub

Open the dashboard hub at Voice → On-call & escalation and work the loop with a test incident, open → ack → resolve:
  1. Resolve, then plan. Paste the rotation and policy from Steps 1–2 into the two read forms. Confirm on_call names who you expect and the timeline lists four pages at offsets 0 / 300 / 900 / 1500.
  2. Open a test incident in the incident driver. The status badge flips to OPEN and the due list names step 0’s channels.
  3. Acknowledge, then resolve. The badge walks ACKNOWLEDGED → RESOLVED and every later tick returns an empty due list with no next wake-up.
  4. Work the negative path. Ack the resolved incident and confirm the driver reports 409 incident_transition_invalid — the API rejects an out-of-order transition instead of corrupting your snapshot. Reassign after resolution rejects the same way.
The deep dive numbers the full six-phase drill, including the reassign-override phase, and maps each dashboard form to its scope (messages:read for the two read forms, messages:write for the driver).

​
Step 4 — close the loop: wire the four endpoints into your scheduler

The dashboard drill and a live scheduler call the same four endpoints. The loop your scheduler runs:
  1. POST /api/v1/oncall/resolve when you open an incident — the current holder becomes step 0’s page target.
  2. POST /api/v1/oncall/escalation/plan once per policy change — cache the flattened timeline in your own store.
  3. POST /api/v1/oncall/incident/tick on a timer — send each due page through the Messages API, persist the returned pages_fired mark, and sleep until next_tick_at.
  4. POST /api/v1/oncall/incident/transition on operator action — ack { by } halts the escalation; resolve closes it; a 409 means your stored snapshot is stale and you should re-read it.
You own persistence on every on-call endpoint — the incident snapshot’s status and pages_fired mark are the only state the API asks you to keep, and each page fans out through the Messages API, where your sender ids and quiet-hours policy apply as they do to any other send. When the drill sequence and the live scheduler agree, the rotation is live; revisit whichever guide owns the sub-task you are changing, not all three.

​
When this stack is the wrong page

Two boundary cases route elsewhere:
  • First-time contact-center setup. If you are wiring a contact center from nothing — softphones, queues, agent login, the whole surface — the on-call guides are not the answer. Follow the voice go-live checklist, which sequences the wiring end-to-end; on-call escalation is a dispatch layer you attach after that surface is up.
  • A live incident that needs a human paged now. The reverse also holds: mid-incident, with a responder to reach, the checklist is the wrong page and this trio is the right one — open the deep dive for the operator path or the alerting guide if you are scripting the page.

​
Sample payloads for the four endpoints

Every response below is the { data, meta } envelope; meta (request id, timestamp) is omitted for readability. Requests assume the policy from Step 2.

​
POST /api/v1/oncall/resolve

Request
200
shift_index counts completed shifts since the anchor; on_call is members[shift_index % len(members)]. Omit at to resolve the current instant.

​
POST /api/v1/oncall/escalation/plan

Request
200
Each step’s offset is the cumulative sum of the escalate_after_seconds values before it, and round 1 stacks on round 0’s total. Rotation targets re-resolve at each page’s fire_at — the previews here resolve to usr_2, the shift holder at those instants.

​
POST /api/v1/oncall/incident/tick

Request
200
The first tick ran five and a half minutes after open, so both round-0 pages come back due in one response. Persist pages_fired: 2; a replayed tick with that mark re-returns an empty due_pages, never a double page. next_tick_at is the only scheduling input you need.

​
POST /api/v1/oncall/incident/transition

Request — ack
200 — ack from open
409 — ack of a resolved incident
Persist the returned snapshot after every call. resolve is valid from open or acknowledged; reassign { policy } restarts the timeline at step 0 under the new policy and resets pages_fired to 0. Every other combination — ack from acknowledged, ack or reassign after resolved — answers 409 incident_transition_invalid and changes nothing, so a stale snapshot in your dispatcher is surfaced, not applied. The On-Call API reference carries the full transition matrix and per-language samples.

​
See also