{ "data": { "rotation_name": "Platform primary", "at": "2026-09-25T09:15:00.000Z", "on_call": "+15551234567", "shift_index": 0, "shift_start": "2026-09-21T00:00:00.000Z", "shift_end": "2026-09-28T00:00:00.000Z", "next_on_call": "usr_primary_03", "next_handoff_at": "2026-09-28T00:00:00.000Z" }, "meta": { "request_id": "req_9042", "timestamp": "2026-09-25T09:15:00.000Z" } }

On-call deep dive

Devotel Orbit’s on-call surfaces answer the four questions incident dispatch depends on: who holds the pager right now, who is next when they miss it, what the escalation timeline will actually do, and where that timeline stands for a live incident. Two operator guides cover the endpoints one at a time — the on-call alerting guide for the endpoint-by-endpoint build and the escalation runbook for tuning timeouts and repeat rounds. This page is the consolidated operator walkthrough: one read that takes you from an empty rotation to a rehearsed pager hand-off, using the dashboard hub for setup and the On-Call API for automation.

Everything here is a control your tenant owns: rotations, policies, channels, thresholds, and the incident record all live in your account or in your own store. Orbit never pages anyone on the oncall route group — every endpoint is pure compute over the request you send, and the actual send exits through the Messages API, where your sender ids, quiet-hours policy, and delivery webhooks apply exactly as they do to any other send.

What the dashboard hub covers

The on-call hub lives at Voice → On-call & escalation. It is one page with four working components, and each one wraps one endpoint of the POST /api/v1/oncall route group:

Component	What it runs	What you read out of it
Who’s on call	`POST /api/v1/oncall/resolve`	The rotation form returns the current on-call member, the shift window, the next member, and the next hand-off instant. Setting a “Resolve at” time replays the rotation at any instant — the way to verify a roster before it goes live, or to answer “who was on call when this fired.”
Escalation timeline	`POST /api/v1/oncall/escalation/plan`	The policy form adds steps (a rotation or a fixed member list as the target, the channels to page, an acknowledge window) and returns the flattened timeline: every page’s round, step, offset, fire instant, targets, and channels. Preview it before an incident depends on it.
Incident driver	`POST /api/v1/oncall/incident/tick` and `POST /api/v1/oncall/incident/transition`	A live test incident you can advance, acknowledge, resolve, and reassign — a status badge, the pages-due list, and the next wake-up instant on every step.

Resolve and plan are read-only and need the messages:read scope. The incident driver mutates incident state (acknowledge, resolve, reassign) and needs messages:write. Non-technical stakeholders carry the read role; the operators who acknowledge and resolve carry write.

Wire the route group

Every dashboard form maps to a POST on the /api/v1/oncall route group, which lets your scheduler, dispatcher, or incident script do the same work the page does. Four endpoints, one authorization ladder:

Rotations (/resolve). Model the rotation you already run: an anchor, a cadence, and an ordered member list. DST is correct because every shift is exactly one shift length after the anchor — there is no timezone math to tune. Backdate at to audit who held the pager at an arbitrary instant.
Policies (/escalation/plan). Chain steps (rotation or users targets) with an acknowledge window (escalate_after_seconds, default 300) per step and a policy-level repeat loop. The plan response hands you absolute fire_at offsets you can schedule against — the timeline an incident driver walks.
Tick (/incident/tick). Drive a live incident on your own timer: pass the snapshot, receive the pages due now, the new pages_fired high-water mark to persist, and next_tick_at. A halted (acknowledged or resolved) incident returns due_pages: [] and next_tick_at: null, so your scheduler stands down.
Transition (/incident/transition). Apply ack, resolve, or reassign. Invalid transitions — acknowledging a resolved incident, or reassigning after resolution — answer 409 incident_transition_invalid rather than corrupting your state.

Read roles (owner, admin, developer, viewer) reach the first two; drive roles (owner, admin, developer) reach tick and transition. The same split shows up in the dashboard: clearing a page to a _read key previews the timeline but hides the driver’s acknowledge and resolve buttons. The path on the wire stays POST /api/v1/oncall/<op>; the full endpoint, scope, and field reference is the On-Call API reference.

Calling the API directly

Everything the hub does is a POST your scheduler can make verbatim. The first call below resolves a rotation; the On-Call API reference carries the per-endpoint field tables, and the worked sequence under it chains two calls into an actual page.

curl -X POST https://api.orbit.devotel.io/api/v1/oncall/resolve \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rotation": {
      "name": "Platform primary",
      "cadence": "weekly",
      "anchor": "2026-09-21T00:00:00Z",
      "members": ["+15551234567", "usr_primary_03"]
    }
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

// Generic request() — the oncall group has no typed helper yet; auth,
// retries, and the { data, meta } envelope stay identical.
const { data } = await orbit.request("POST", "/oncall/resolve", {
  rotation: {
    name: "Platform primary",
    cadence: "weekly",
    anchor: "2026-09-21T00:00:00Z",
    members: ["+15551234567", "usr_primary_03"],
  },
});
console.log(data.on_call); // "+15551234567"

from orbit import Orbit

client = Orbit(api_key=os.environ["ORBIT_API_KEY"])

# Same escape hatch as the Node SDK — generic request() over the group.
resolved = client.request(
    "POST",
    "/oncall/resolve",
    json_body={
        "rotation": {
            "name": "Platform primary",
            "cadence": "weekly",
            "anchor": "2026-09-21T00:00:00Z",
            "members": ["+15551234567", "usr_primary_03"],
        }
    },
)
print(resolved["data"]["on_call"])  # "+15551234567"

Omit at to resolve for the current instant. Backdate it to audit who held the pager when an alert fired — the window math is deterministic, so a replayed resolve returns the historically correct shift.

{
  "data": {
    "rotation_name": "Platform primary",
    "at": "2026-09-25T09:15:00.000Z",
    "on_call": "+15551234567",
    "shift_index": 0,
    "shift_start": "2026-09-21T00:00:00.000Z",
    "shift_end": "2026-09-28T00:00:00.000Z",
    "next_on_call": "usr_primary_03",
    "next_handoff_at": "2026-09-28T00:00:00.000Z"
  },
  "meta": {
    "request_id": "req_9042",
    "timestamp": "2026-09-25T09:15:00.000Z"
  }
}

Read data.on_call as the member to page right now and data.next_on_call as the member who takes over at data.next_handoff_at. The shift_start / shift_end pair brackets the current shift exactly, so a due-at calculation never needs timezone math.

Escalate, then page

The worked sequence: flatten a policy with /escalation/plan (read scope), then fan the first due page out through Messaging (write scope) on the channels the plan names.

Plan the escalation

Send the policy definition (a users step targeting a fixed member list reads as a responses row in the API console) and read the flattened pages[] timeline back:

Responses shape — plan

{
  "responses": [
    {
      "step": 0,
      "targets": ["+15551234567"],
      "channels": ["push", "sms"]
    }
  ]
}

Each row gives you the step, the resolved targets, and the channels to page — the exact fan-out list for the send below. Rotation targets re-resolve at each page’s fire_at, so a hand-off mid-escalation still reaches the right member.

Send the page through Messaging

Pass each resolved target as to in a POST /api/v1/messages/sms send. The send exits through the same Messaging pipeline as the rest of your traffic — your sender ids, quiet-hours policy, and delivery webhooks apply.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "body": "Sev-1: checkout error rate above threshold. Ack in the incident console."
  }'

Python

import os, requests

policy = {
    "name": "Sev-1 platform",
    "steps": [
        {
            "target": {"type": "users", "members": ["+15551234567"]},
            "channels": ["push", "sms"],
            "escalate_after_seconds": 300,
        }
    ],
}
headers = {
    "X-API-Key": os.environ["ORBIT_API_KEY"],
    "Content-Type": "application/json",
}
plan = requests.post(
    "https://api.orbit.devotel.io/api/v1/oncall/escalation/plan",
    headers=headers,
    json={"policy": policy},
).json()["data"]
first = plan["pages"][0]
if "sms" in first["channels"]:
    requests.post(
        "https://api.orbit.devotel.io/api/v1/messages/sms",
        headers=headers,
        json={
            "to": first["targets"][0],
            "body": "Sev-1: checkout error rate above threshold. "
                    "Ack in the incident console.",
        },
    )

See Send an SMS for the full send contract.

The same resolve-then-send recipe is laid out step-by-step at the On-Call API reference — this guide keeps the raw calls; the reference keeps the field tables. The chain below pages the current on-call member over push and SMS within the first minute, falls to a named backup over voice after five minutes if nobody acknowledges, and repeats the loop once. Distinct responders touch the incident at distinct offsets — that is the hand-off.

Open. Your alert source (a health check, an SLO alarm, a tenant-defined trigger) opens the incident: status: "open", pages_fired: 0, started_at set. Nothing pages yet.
First page. At offset 0 a tick reports step 0 due, with the rotation target resolved at that instant — the current on-call member — and channels ["push", "sms"]. Your dispatcher fans the page out through the Messages API on those channels.
Hand off to the fallback. No ack lands within the 300-second window, so a tick at offset 300 reports step 1 due — usr_9 over ["voice"]. Voice is the fallback channel on purpose: a call cuts through a muted phone in a way a text does not.
Acknowledge anywhere. The responder acknowledges at any offset. Your driver calls /incident/transition with ack { by }; the returned snapshot flips to acknowledged and every later tick returns due_pages: [], next_tick_at: null.
Repeat round. If the first round fires every page and nobody acknowledges, repeat: 1 loops the policy once more — the rotation re-resolves at each fire instant, so a hand-off mid-incident still pages the right member. At the end of all rounds tick reports status: "exhausted".

The escalation runbook walks this same chain with the four-row timeline table and the offset arithmetic spelled out.

Where agent distress lands

On-call accepts event sources, not just timers. One source you already have: the agent distress alert model defines the softphone panic button, which flips a live call into recorded state and raises a supervisor alert. A dispatch rule turns that alert into a page: the rule you call on the alert is the same escalation policy you preview in the dashboard, so “page the supervisor on shift” is the rotation step from the example above. Define the alert-to-incident mapping in your dispatcher; the On-Call API evaluates the rest. Subscribe to delivery status so a page that never landed is distinguishable from a responder who never acknowledged, before the step window elapses.

Try it end-to-end in test mode

Rehearse the lifecycle from the dashboard with a signed-in test run. Sequence matters, not speed — walk every phase.

Rotate. Define a rotation with two members, a weekly cadence, and today’s anchor. Resolve it with and without a time set, and confirm member[0] is the notional holder when the anchor is in the future.
Plan. Build the two-step policy from the example above, keeping repeat: 1. Confirm the table lists four pages: round 0 offsets 0 and 300, round 1 offsets 900 and 1500.
Open incident. In the incident driver set an optional incident id and the current time, then Open incident. Verify the status badge flips to OPEN and the due list names step 0’s channels.
Ack. Call Acknowledge. Confirm the badge flips to ACKNOWLEDGED and every later tick returns an empty due list with no next wake-up.
Resolve. Call Resolve against the acknowledged incident. Confirm the badge flips to RESOLVED and the driver stops — the lifecycle is terminal.
Negative paths. Acknowledge the resolved incident and confirm the 409 incident_transition_invalid error. Reassign a resolved incident and confirm the same. Then open a fresh incident and call Reassign on it: the timeline restarts from step 0 under the new policy — the supported override.

When the sequence runs clean against the dashboard, wire the same four endpoints into your scheduler and run the cycle against your own incident store.

WhatsApp

Developer console

Contact center

Guides

Admin

Messaging Controls

Audience & Support Tools

On-call deep dive: from dashboard hub to a working pager

On-call deep dive

What the dashboard hub covers

Wire the route group

Calling the API directly

Escalate, then page

Where agent distress lands

Try it end-to-end in test mode

See also

​On-call deep dive

​What the dashboard hub covers

​Wire the route group

​Calling the API directly

​Escalate, then page

​Pager hand-off — a worked example

​Where agent distress lands

​Try it end-to-end in test mode

​See also

On-call deep dive

What the dashboard hub covers

Wire the route group

Calling the API directly

Escalate, then page

Pager hand-off — a worked example

Where agent distress lands

Try it end-to-end in test mode

See also