The queue callback model

A queue callback answers one question — “does Orbit let a caller stop holding without losing their turn?” — with yes. A caller who has waited long enough can opt out of the physical hold, keep a virtual place in the queue’s dispatch order, and receive an outbound callback when that place matures. The callback is a first-class row in your org’s data: it has a lifecycle you can watch, a status you can filter on, operator actions you can run from the dashboard, and a per-queue SLA objective that alerts before a backlog ages out. This page is the concept map: what a queue callback is, where you configure it, how dispatch decides when to dial, and how outcome codes tie back to the queue’s service-level reporting. The step-by-step operator playbook for a breaching queue (objectives, forecast, escalation ladder, on-call loop) stays on the queue SLA forecast-callback runbook — this page owns the customer-facing setup and model so that runbook never has to re-teach them. Every control named here is tenant-owned: your queues, your overflow action, your SLA policy, your operator actions. Callbacks dispatch exclusively over the Devotel softswitch — you never configure a third-party outbound trunk to activate them.

1. What a queue callback is — holding without a phone to the ear

A queue callback is a virtual hold: the caller’s place in the FIFO dispatch order survives their hangup. The caller opts in (the queue’s IVR voices a “press 1 for a callback” offer, or the SLA entry gate steers them to it), the platform records a callback request, and the caller hangs up. When their turn would have arrived, Orbit dials them back and connects them to an agent — as if they had kept the telephone silent on the desk the whole time. Two opt-in flavors produce the same promise through different doors:

Flavor	When the offer plays	What the dispatcher waits for
In-queue (position-saving)	While the caller is still holding — sometimes before any breach, flagged by the SLA pre-suggest forecast	Agent availability — the caller keeps an implicit place in line
Overflow (time-driven)	After the caller has waited past the queue’s overflow threshold	A retry-ladder timer plus an agent at the far end

Both flavors land as one trackable request per caller — a duplicate press (a jittered press-1, an IVR retry) is refused rather than double-booked, so a caller never receives two callbacks for one hold. A third, sibling flavor is agent-driven: a disposition-driven callback the agent schedules at wrap-up (follow_up + a displacement), dispatched at due time through the same pipeline. The model below covers the caller-driven pair; the agent-driven sibling shares their dispatcher but starts at the wrap-up code, not the IVR offer. The caller’s promise at opt-in time is recorded with the request: the queue they were holding on, their (masked) caller id, the estimated wait they were quoted, and — for scheduled callbacks — the appointment window they picked. That quote-vs-reality gap is what the queue’s callback SLA policy later measures.

2. Configuring callbacks on a queue

Callback behavior is queue configuration wired in two dashboard surfaces, not a separate feature to enable:

Set the queue’s overflow action to Callback. Open Voice → Queues, pick the queue, and on its edit dialog set the overflow action to Callback. The Voice → Callbacks page short-circuits this for you: when no callbacks exist yet, its empty state offers a queue picker plus a Configure callback overflow link that deep-links straight into that queue’s overflow setting with the Callback value preselected.
Voice the offer to the caller. The in-queue press-1 offer lives in the queue’s IVR path — the overflow action alone catches callers who blow past the threshold; the in-queue offer catches the ones who opt out earlier. The full helper/forecast wiring that raises the offer the moment the queue starts breaching is the gate-and-forecast pair documented on Inbound queue SLA forecast + virtual callback gate.
Set the queue’s SLA target (targetServiceLevelSeconds) so the forecast and the callback SLA policy have a bound to measure against. A queue with no SLA target still offers and dispatches callbacks — it just never forecasts, never gates, and never alerts on an aging backlog.

The voice queues guide walks create-and-staff step by step; the callback field inventory (API shapes, scheduling windows, SLA policy) is the reference for every field named here.

3. How the callback trigger works

The callback offer is decided at queue entry, before a new caller adds to FIFO depth. The queue evaluates the same live inputs used by the wallboard: waiting depth, recent average handle time, eligible agents, the oldest wait, and the tenant-owned targetServiceLevelSeconds. A missing target keeps this gate fail-open; it does not invent a forecast. The trigger has two independent breach paths:

Forecast breach: waiting callers × recent average handle time ÷ available agents is greater than the queue’s target. With no eligible agents, the projected wait is unbounded.
Head-of-line trip: the oldest existing wait has already crossed the target. This check catches a stalled queue even when the new caller’s position math looks acceptable, including a queue whose live depth is near zero while an existing head is still aging.

The queue then applies slaCallbackPolicy: suggest keeps the caller in FIFO and flags the supervisor surface, while block refuses queue entry with 503 and slaCallbackBlocked: true, sending the caller to the press-1 consent flow. The consent flow, not the refusal itself, creates the callback row. Use this decision tree when tracing a trigger:

if targetServiceLevelSeconds is unset:
  accept queue entry (fail open)
else if oldest_wait_seconds > targetServiceLevelSeconds:
  breach = "head_of_line"
else if available_agents == 0 or projected_wait_seconds > targetServiceLevelSeconds:
  breach = "forecast"
else:
  accept queue entry normally

if breach and slaCallbackPolicy == "suggest":
  accept entry + flag callback suggestion
if breach and slaCallbackPolicy == "block":
  return 503 { slaCallbackBlocked: true } + play press-1 offer

A successful press-1 consent hands the request to the callback dispatcher. The wiring is deliberately shared: the queue gate plays the consent prompt, the consent handler writes one tenant-scoped callback request, and the dispatcher claims that request only when its queue-position, retry, or appointment gate is due. It then hands the outbound leg to the Devotel softswitch and applies the emergency-number and tenant calling-window guards before dialing. There is no separate forecast dispatcher to reconcile with the callback list. The dispatcher is one shared machine for every callback flavor. Three questions decide what happens to a pending row, in order: When does it become due? An in-queue row matures on queue position — the dispatcher waits for agent availability as if the caller were still holding at their saved position. An overflow row matures on its retry-ladder tick — the first attempt fires on opt-in; each failed attempt re-schedules on the backoff ladder until the queue’s retry budget is spent. A scheduled row matures at its appointment: a scheduled_for target or a booked window, with the row held quiet in FIFO until the window opens. Whichever gate applies, no row dials before it is due. What guards the dial? Two tenant- and platform-level guards sit in front of every attempt, exactly as they do for any other outbound leg: a callback that would resolve to an emergency short code is blocked outright, and a callback that would land outside the recipient’s calling window is held, not dialed. Callers outside the window never hear a ring; the row simply stays pending until the window opens. What if the caller doesn’t pick up? A no-answer or busy far end is not terminal on the first ring — the retry ladder re-schedules the attempt. The ladder is bounded: when the queue’s retry budget exhausts, the row flips to failed and stops consuming dials. An abandoned outcome is the caller-side mirror — the dial connected at our end but the far end hung up before an agent was bridged. A missed appointment window (MISSED_SCHEDULED_WINDOW) is terminal by design past the window’s end — the agreed promise was a window, not an open-ended backlog. While a row is pending, operators have three controls on the Voice → Callbacks list: Cancel (terminal, idempotent — a re-cancel is a clean no-op), Retry now (re-enqueue for immediate dispatch, refused while the row is already dialing), and Re-prioritize (pull the row to the front of the pending FIFO). The caller holds the same cancel capability through their public tracking link — the same transition, from their side.

Attempt lifecycle and fields

Read callback attempts through GET /api/v1/voice/callbacks?queue_id={id} (the operator list surface described in the callback field inventory). The list returns the tenant-scoped callback row and its dispatch counters; it does not expose a second, queue-global callback store. These fields explain a delayed or terminal callback:

Field	Meaning
`id`	The callback request identifier. Use it for operator actions and support traces.
`queue_id`	The queue that supplied the virtual position.
`status`	`pending`, `dialing`, `connected`, `failed`, `abandoned`, or `canceled`.
`consented_at`	When the caller accepted the callback offer.
`created_at`	When Orbit created the callback request.
`attempts`	Number of dial attempts, including retries.
`connected_at`	When the callback connected; `null` until then.
`wait_seconds_before_callback`	How long the caller had waited when they accepted the offer.
`scheduled_for`, `scheduled_window_start`, `scheduled_window_end`	Optional appointment point or window that holds dispatch until it is due.
`estimated_wait_seconds`	The offer-time estimate, when the queue could calculate one.

The conceptual attempt lifecycle is queued → dispatched → accepted or queued → expired: the public row calls those phases pending → dialing → connected and records an expiry as failed with the terminal reason (for example, MISSED_SCHEDULED_WINDOW). abandoned means the callback leg connected but the caller ended it before the agent bridge. The request stays in the tenant that owns the queue, and retries increment attempts rather than creating a second consent row. For the complete response shape and mutations, use the voice callbacks and scheduling reference.

Decode a blocked queue entry

A queue-entry 503 with slaCallbackBlocked: true describes the entry gate, not a failed callback attempt. Use this matrix before looking at callback rows:

Response signal	Gate that fired	What to check
`503` + `slaCallbackBlocked: true` + `projectedWaitSecs > slaThresholdSecs`	Forecast breach	Compare the projected wait with staffing and `targetServiceLevelSeconds`; raise eligible staffing or keep the diversion.
`503` + `slaCallbackBlocked: true` while `stats.longest_wait` exceeds `slaThresholdSecs`	Head-of-line trip	Inspect the oldest waiting call and agent eligibility; this can fire even when depth is 0 or 1.
`503` + `slaCallbackBlocked: true` on every entry with idle agents	Target is too low, or `block` was enabled before dispatch was wired	Confirm `slaCallbackPolicy`, the target, and the press-1 dispatcher path. Use `suggest` while validating.
`503` without `slaCallbackBlocked`, with `error.code: QUEUE_DEPTH_CAP_REACHED`	Queue-capacity gate	Read depth and `acd_queue_max_depth`; this is not an SLA forecast. Follow queue capacity gates.

The complete refusal checklist and request-id collection steps are in Troubleshooting: queue SLA forecast callback gate.

Worked registration responses

When the caller presses 1, the queue’s call-control layer records consent through the internal callback-consent handoff. Your application does not call this internal route directly; it shows the actual registration payload so you can recognize the event in a trace:

curl -X POST "https://api.orbit.devotel.io/api/v1/internal/voice/callback-in-queue-consent" \\
  -H "X-Internal-Token: $ORBIT_INTERNAL_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "tenant_id": "tenant_123",
    "queue_id": "queue_supp",
    "original_call_id": "call_01J...",
    "caller_phone": "+15551234567",
    "caller_id_e164": "+15551234567",
    "queue_position_at_optin": 4,
    "wait_seconds_before_optin": 87,
    "priority": 0
  }'

HTTP/1.1 201 Created
{
  "data": {
    "id": "callbackInQueueRequest_01J...",
    "status": "pending",
    "estimated_wait_seconds": 120
  },
  "meta": { "request_id": "req_01J..." }
}

If the queue is on block and the forecast gate fires before consent, the entry is refused and no callback attempt exists yet:

HTTP/1.1 503 Service Unavailable
{
  "slaCallbackBlocked": true,
  "slaThresholdSecs": 30,
  "projectedWaitSecs": 87,
  "overflowAction": "callback",
  "queueId": "queue_supp",
  "callControlId": "cc_..."
}

Read the blocked response as an instruction to play the consent offer, not as proof that a callback was registered. The attempt is created only after the caller opts in.

Capacity and overflow are separate gates

The SLA callback gate is not a replacement for queue capacity. slaCallbackBlocked: true means the queue’s forecast or head-of-line objective fired; QUEUE_DEPTH_CAP_REACHED means the tenant-owned acd_queue_max_depth refused more FIFO depth. A queue can be below its depth cap and still breach its SLA, or hit its depth cap before the SLA forecast crosses its target. Diagnose those responses independently in queue capacity gates. Overflow-chain validation is a third gate. A queue config write fails with OVERFLOW_QUEUE_NOT_FOUND, OVERFLOW_QUEUE_CHAIN_CYCLE, or OVERFLOW_QUEUE_SELF_CHAIN when the configured sibling path is missing or loops. Fix that chain before relying on an overflow callback; the SLA gate’s press-1 path and the max-wait overflow action share callback dispatch, but they do not share the same entry decision.

4. Reading callback outcomes — statuses, codes, and the SLA reports

Every callback resolves to exactly one outcome status, and that status is your audit trail:

Status	Meaning
`pending`	saved, due or not yet mature, waiting on the dispatcher
`dialing`	an attempt is in flight right now
`connected`	the caller answered and was bridged to an agent
`failed`	the retry budget exhausted without a connection
`abandoned`	the dial connected, but the caller’s side terminated before the bridge
`canceled`	terminal by an operator or by the caller’s public link

The Voice → Callbacks page filters on these statuses plus the queue, and its summary strip (total / pending / connected / average wait) lets a supervisor see the backlog without pulling a report. Two detail registers accompany the statuses: avg_wait_seconds compares the promise quoted at opt-in against the dispatch latency actually delivered, and the in-queue summary’s avg_queue_position_at_optin tells you how deep into the line callers typically bail — the number you tune the offer’s trigger point against. Outcome codes are the input, not the report. The report is the queue’s SLA surface: a per-tenant callback SLA policy (per queue — max age of the oldest pending callback, max pending count, notify surfaces) turns “how old may the oldest callback get before someone is paged” into a stored objective, and the queue’s existing SLA analytics and alert rules consume the same outcome stream the list page renders. Read the policy/alert wiring on the callbacks scheduling + SLA reference and the queue’s overall service-level loop on the queue SLA escalation policies concept.

5. What this page does NOT cover — the breaching-queue ops playbook

This page explains what a callback is and how to configure it. The moment the queue is breaching — objectives missed, the forecast tipping, the escalation ladder firing — is an operational runbook, not a concept: read Queue SLA forecast-callback runbook for the end-to-end playbook (define the objective, wire the breach policy and escalation ladder, test the breach path with a synthetic window, and work the on-call loop when it fires). The runbook assumes this page’s model; this page deliberately never explains a breach response.

Set up and run voice queues — create the queue, staff it, and set the overflow action this page names.
Voice queue callbacks with SLA policies and scheduling — the API field inventory for every surface named here, plus scheduling windows and disposition-driven callbacks.
Inbound queue SLA forecast + virtual callback gate — the entry gate that steers a new caller to the callback offer before they ever join the line.
Inbound queue SLA forecast: pre-suggest callback before breach — the advisory forecast that raises the offer flag on waiting callers early.
Queue SLA forecast-callback runbook — the ops playbook for a breaching queue; the model on this page is its prerequisite.
What does a queue SLA forecast callback actually measure? — the concise FAQ answer and the forecast formula this page expands.
Troubleshooting: queue SLA forecast callback gate — decode the 503 decision body and collect the right diagnostics.
Troubleshooting: queue capacity gates — separate depth-cap and overflow-chain refusals from SLA gating.
The ACD queue model: presence, skills, dispatch, and overflow — the FIFO dispatch and presence machinery the callback’s virtual hold plugs into.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

The queue callback model: virtual hold, dispatch, and outcomes

The queue callback model

1. What a queue callback is — holding without a phone to the ear

2. Configuring callbacks on a queue

3. How the callback trigger works

Attempt lifecycle and fields

Decode a blocked queue entry

Worked registration responses

Capacity and overflow are separate gates

4. Reading callback outcomes — statuses, codes, and the SLA reports

5. What this page does NOT cover — the breaching-queue ops playbook

​The queue callback model

​1. What a queue callback is — holding without a phone to the ear

​2. Configuring callbacks on a queue

​3. How the callback trigger works

​Attempt lifecycle and fields

​Decode a blocked queue entry

​Worked registration responses

​Capacity and overflow are separate gates

​4. Reading callback outcomes — statuses, codes, and the SLA reports

​5. What this page does NOT cover — the breaching-queue ops playbook

​Related

The queue callback model

1. What a queue callback is — holding without a phone to the ear

2. Configuring callbacks on a queue

3. How the callback trigger works

Attempt lifecycle and fields

Decode a blocked queue entry

Worked registration responses

Capacity and overflow are separate gates

4. Reading callback outcomes — statuses, codes, and the SLA reports

5. What this page does NOT cover — the breaching-queue ops playbook

Related