> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> How a queue callback works in Orbit — the caller opts out of holding and keeps a virtual place, the queue returns a callback when the position matures, and every outcome code lands in one auditable list tied to the queue's SLA reporting.

# 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](/guides/queue-sla-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](/voice/sla-breach-forecast-callbacks) | 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](/voice/callbacks-scheduling) 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:

1. **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.
2. **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](/voice/queue-sla-forecast-callback).
3. **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](/guides/voice-queues) walks create-and-staff step by step; the [callback field inventory](/voice/callbacks-scheduling) (API shapes, scheduling windows, SLA policy) is the reference for every field named here.

## 3. How the callback is placed — queue-position maturity, abandon, and retry

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.

## 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](/voice/callbacks-scheduling) and the queue's overall service-level loop on the [queue SLA escalation policies concept](/voice/queue-sla-escalation-policies).

## 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](/guides/queue-sla-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.

## Related

* [Set up and run voice queues](/guides/voice-queues) — create the queue, staff it, and set the overflow action this page names.
* [Voice queue callbacks with SLA policies and scheduling](/voice/callbacks-scheduling) — the API field inventory for every surface named here, plus scheduling windows and disposition-driven callbacks.
* [Inbound queue SLA forecast + virtual callback gate](/voice/queue-sla-forecast-callback) — 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](/voice/sla-breach-forecast-callbacks) — the advisory forecast that raises the offer flag on waiting callers early.
* [Queue SLA forecast-callback runbook](/guides/queue-sla-callback-runbook) — the ops playbook for a breaching queue; the model on this page is its prerequisite.
* [The ACD queue model: presence, skills, dispatch, and overflow](/concepts/acd-queue-model) — the FIFO dispatch and presence machinery the callback's virtual hold plugs into.