Skip to main content

​
Queue SLA forecast-callback runbook

A queue SLA only works when four pieces run as one system: the objective one line sets, the forecast that flags a breach before the caller breaches, the breach policy that decides what fires, and the on-call workflow that reacts in minutes, not in the next morning’s report. This guide stitches the two concept pages — the per-queue SLA escalation policies objective and the forecast + virtual callback gate entry gate — into a single runbook you can wire end to end. Each piece is tenant-owned: your thresholds, your webhook, your escalation ladder, your on-call response. Orbit never dials a callback you didn’t consent to, and tenant-owned is the only posture this page documents — the fallback webhook and the escalation actions are your endpoints and your people.

​
1. Objectives and SLA targets

A queue’s SLA target is a single promise: X% of callers answered within Y seconds, measured over a rolling window. Every surface that reads the SLA — the wallboard’s service-level metric, the forecast, the breach policy, and the alarm rules — reads the same per-queue target, so changing the queue changes the whole pipeline at once. Pick the objective before you wire anything, because the whole runbook depends on the answers to these two numbers:
  • Answer-within target (targetServiceLevelSeconds, 5–300, default 20): the longest a caller should wait before someone answers.
  • Target percentage and window (targetPercentage and evaluationWindowMinutes in the breach policy): how strict the promise is, and over what window you measure it. A payments queue promising 95% in 20s breaches sooner and escalates differently from a support queue promising 80% in 30s.
A queue with no targetServiceLevelSeconds opts out of every SLA surface: nothing forecasts, nothing alerts. Setting the target is the opt-in.

​
2. Build the SLA policy — thresholds and escalation per queue

The breach policy lives on the queue itself, at /api/v1/voice/queues/{id}/sla-breach/policy. The policy defines the promise (target % + threshold + window) and the response (a one-shot breachAction, or a multi-rung escalationSteps[] ladder). Write the whole policy in one PUT:
Read it back with GET .../sla-breach/policy; remove it entirely with DELETE. The escalation ladder supersedes the one-shot breachAction as soon as any step exists — see Per-queue SLA breach alerting and escalation policies for the full field inventory, the cooldown gate, and the policy-lifecycle (a policy write is audit-logged, a deletion is hard).

​
3. Wire the forecast callback: attach, fallback webhook, test the breach path

The forecast gate closes the loop: without it a breaching queue only gets worse, because every new arrival accrues hold the queue already can’t afford. Attach it by patching the queue config:
  • suggest — the forecast computes a suggest verdict, the caller joins normally, and the supervisor surface flags “press 1 for a callback advised.” Take this when you want the cue without touching the caller path.
  • block — when the forecast says the queue is breaching, entry is refused and the caller exits to the press-1 virtual-callback consent flow with position saved. Take this once the callback dispatcher is wired.
The fallback webhook is the escalation rung (or one-shot breachAction) you pointed at an HTTPS endpoint in step 2 — webhook, slack_webhook, or teams_webhook. Test the breach path with a synthetic queue-load scenario: drive real, bounded test traffic into the queue until the window you measure misses the target, then push that window to the breach scan and confirm both legs:
Because the scan is the trigger your monitoring loop drives, you can test the whole pipeline — the breached verdict, the escalation rung firing, the webhook landing — with a synthetic window of your own construction long before a real surge ever lands. See Inbound queue SLA forecast + virtual callback gate for the gate’s full decision response (the 503 + slaCallbackBlocked: true contract).

​
4. Reading the queue-health signals

Three endpoints tell you where the queue stands; read them together:
  • GET /api/v1/voice/queues/{id}/live — live queue stats plus fired alert rules over SSE. The forecast-flagged heads surface here as a supervisor advisory flag, so the wallboard’s “press-1 advised” cue and the entry check can never drift (they run the same decision engine).
  • GET /api/v1/voice/queues/{id}/sla-breach/events — the newest-first breach log (up to 200 entries): observed service level, the policy in force, and the surfaces that actually fired. The last field is your audit trail — what the ladder did, not what it was configured to do.
  • The scan response — breached: true/false, observed_service_level, and alert_fired tell you the forecast-vs-measured gap; the breach log tells you whether the alert actually went out.
The forecast fires on a projected breach (the head’s predicted wait meets the target before the window misses it); the breach policy fires on a measured window. Watch the forecast for the early warning; the breach log and the alarm rules carry the record.

​
5. Runbook — what on-call does at breach time

When an escalation rung fires — the webhook lands, the Slack card posts, the page_supervisor action pages your paging tool — the breach is a routing signal, not a post-mortem stat. On-call works the same loop:
  1. Ack the alert. The breach log recorded the route and which rungs fired; open GET .../sla-breach/events to confirm the route before you act on it.
  2. Offer the callback. If the gate is on suggest, that is the supervisor’s cue to relieve the queue — a supervising agent or an automated flow can trigger the press-1 callback for the flagged heads. If the gate is on block, new arrivals are already being diverted.
  3. Escalate. The ladder is already climbing: rung 1 fired at 0 minutes, rung 2 at 15, and so on, on the surfaces you picked (inbox notify, Slack, Teams, your webhook). The escalation keeps paging until the queue recovers or the ladder runs out.
  4. Rebalance and watch. Shift agents to the queue (a reassign rung, or a manual queue-membership change), and watch the wallboard render the queue’s SL back toward target. The wallboard alarm rules — a tenant-wide service_level floor, or a longest_wait guard — are the ad-hoc backstop the breach policy isn’t; wire them alongside so a persistent objective and a one-off threshold both supervise the same rolling window. See Wallboard alarm rules.

​
6. Extend — chained fallbacks across shifts

The breach policy’s ladder is per queue, but the response to it is org-wide. Two patterns extend the runbook across shifts:
  • Chain the fallback across a shift change. A webhook rung points at a single endpoint, but that endpoint can fan out — page the current rotation member, and if no ack lands, hand the incident to the next rotation member. The On-Call API gives you that fan-out with a rotation and an escalation policy you resolve yourself: at breach time your webhook consumer resolves who is on call right now, sends the page through Messages, and steps to the next responder if no one acknowledges. The queue’s escalation policy tells the org something broke; the on-call policy decides who gets paged.
  • Bridge the breach into the org’s alert surface. A webhook or slack_webhook rung lands on the same alert hub the rest of the org uses — a Slack #support-overflow channel for shifts on that queue, an Opsgenie/PagerDuty-style inbound webhook for org-wide paging, or the on-call API’s own rotation if you want the escalation stateless. Either way the runbook is the same: the queue misses its target, the surfaces you named fire, and the next responder gets the page before the callers feel the overflow.
A queue with no policy logs nothing and alerts nothing. Wire the objective, the gate, and the policy together: the forecast gate is strongest when the breach policy and the escalation ladder are already in place behind it.