Skip to main content

​
Voice callback queue console

The callback console at Voice → Callbacks is the operator surface for every virtual-hold callback a caller has asked for. Each row is a request: the queue it came from, the masked caller number, its current status, and when it was requested. From the same page an operator searches and filters the list, claims work with row actions, and completes or cancels callbacks so settled requests leave the queue. Each piece is tenant-owned: callback requests carry caller data (numbers are masked to the first few digits), completion and cancellation are your operators’ actions, and no console action ever places a call outside your account’s outbound path. This guide covers the request → claim → complete/cancel lifecycle. For SLA forecasting and breach response behind the same queues, see the queue SLA forecast-callback runbook.

​
1. What the callback console tracks

The page tracks virtual-hold callbacks — callers who opted to be called back instead of waiting on hold — across three groups:
  • Callback requests — the main list. A caller who met a queue’s overflow and consented to a callback (pressing 1 in the overflow IVR, or through an IVR offerCallback node) becomes one row here. The console paginates this list 50 at a time with a Load more callbacks control, and refreshes it every 30 seconds.
  • In-queue callbacks — position-saving virtual hold. The caller hung up but kept their queue position, so the callback that reconnects them counts as one. This panel is the review-and-cancel surface for those requests.
  • Scheduled callbacks — requests carrying a caller-chosen dial time (a scheduleCallback IVR node captured it, or an agent scheduled the callback from a disposition). Rows surface the due time and flag any request whose scheduled window lapsed while still pending.
Above the list, four stat cards tally the queue’s health: Total, Pending, Connected, and Avg Wait (mean seconds callers waited before their callback). Every row carries the same vocabulary of statuses: Pending and dialing rows are open work. The four terminal statuses are settled outcomes — nothing further fires for them.

​
2. Filters and the empty state

Two controls narrow the list server-side; one narrows it locally:
  • Status filter — All statuses (the default) or one of Pending, Dialing, Connected, Failed, Abandoned, Canceled.
  • Queue filter — All queues (the default) or a single queue, picked by its name. The picker lists every queue the tenant has created, so operators never have to type an opaque queue id.
  • Search — matches the caller number, queue name, or request id against the rows already loaded in the browser. Use Load more callbacks first when the row you’re after is older than the first page — search covers everything you’ve loaded, not just the latest page.
Changing the status or queue filter resets accumulated pages and refetches from the API, so results under the previous filter never spill into the new view. A Clear filters button appears whenever any filter or search term is active, and returns the page to the default view. The page distinguishes two empty states, and only one means “no work”:
  • No callbacks yet — nothing has ever queued. The empty state points at queue configuration: pick a queue and set its overflow action to Callback (jumping straight into that queue’s overflow dialog), or create a queue first if none exists. The console is empty until at least one queue is wired to produce callbacks.
  • No matching callbacks — requests exist, but the active filters or search excluded them all. Clear the filters or widen the search.
The console is restricted to workspace owner, admin, and developer roles. Callback rows carry caller numbers (masked server-side), so it is an operator surface, not a general-staff page.

​
3. Claiming and completing a callback

Each non-terminal row exposes three operator actions from its menu:
  • Retry now — on a Pending row, pulls the next dial attempt to now instead of waiting for the dispatcher’s next pass. Confirmation-free, because it only clamps timing. The action is hidden once a row is dialing — an attempt is already in flight, and forcing a second one would lose to the API’s own guard with a 409.
  • Re-prioritize — on a Pending row, moves the request ahead of its first-in-first-out peers; Move to top sets queue position 1. This leapfrogs other waiting callers, so it sits behind a confirmation dialog. Hidden on the same condition as Retry now.
  • Cancel — removes the request outright. Always confirmation-gated, because cancellation cannot be undone and the caller is never called.
Completion is what the console counts as settled: a callback clears the operator’s open-work view when the attempt connects (the dispatcher confirms both legs of the call and the row lands at Connected) or when an operator cancels it. Terminal rows — Connected, Failed, Abandoned, Canceled — show a disabled Closed label instead of the action menu, and every mutation against them is a no-op at the API as well. Each mutation refetches the list on success, so the row’s new state reflects on the next poll. If another console already settled the row under you, the API answers 404 (row gone) or 409 (no longer pending) and the list refreshes to the truthful state — the row confirms before the page opens the action menu next.

​
4. Callback in IVR flows

The requests the console shows are produced upstream, in the IVR. Two node types enqueue them:
  • offerCallback — terminal node. Offers the caller a virtual-hold callback; a caller who accepts (the press-1 path in the overflow prompt) becomes a console row in the queue the node targets. Offer it from a queue overflow path rather than as a first-class routing choice — callback is the hedge against hold time, not a replacement for answering.
  • scheduleCallback — terminal node. The caller names the dial moment (a DTMF time-selection prompt), and the row lands in the Scheduled callbacks panel with its due time attached instead of riding the immediate attempt ladder.
Both are terminal nodes, so the graph validator accepts them as flow exits — and once a flow contains either, simulate the flow end to end with POST /api/v1/voice/ivr-flows/:id/simulate before attaching it to a number, so you know the consent leg actually reaches the node. The full flow-building walkthrough is Build an IVR flow, and the underlying verbs the runtime emits are in the Programmable Voice DSL reference. The other enqueue path never touches an IVR: a queue whose overflow action is Callback converts overflowed callers into the same kind of row when they consent, and that consent prompt is the press-1 leg described above. The console’s empty state links directly to that overflow configuration when no rows exist yet.

​
5. Breach response

The console tells you what is queued; it does not tell you a queue is about to miss its service-level objective. That forecasting lives one layer up: the queue SLA forecast-callback runbook wires the per-queue SLA objective, the breach forecast, and the escalation ladder (webhook, Slack, paging) that fires when the forecast trips. Read it next if your queues breach SLAs before callers get through — the console is the response surface the runbook’s Offer the callback step works from.

​
Worked example: IVR offerCallback to disposition

End to end, one request through the whole lifecycle:
  1. Enqueue. Your support queue queue_supp overflows at 40 concurrent callers. Its overflow path enters an IVR flow whose terminal node is offerCallback. A caller presses 1 at the “press 1 to keep your place and receive a callback” prompt, hangs up, and a row lands on the console — status Pending, queue queue_supp, caller masked to its first digits.
  2. Find it. Open Voice → Callbacks, pick queue_supp in the queue filter, and the row shows in the Pending view. The Pending stat card ticks up; the list auto-refreshes as the dispatcher works.
  3. Claim it. The dispatcher picks the row in position order and the status moves to Dialing, then Connected when the caller answers and joins an agent — the request is complete and its Closed label disables the action menu. If the queue is hot and a supervisor wants this caller first, they open the row menu while it is still Pending, choose Re-prioritize → Move to top, and confirm.
  4. Disposition. The agent who takes the connected callback ends it with a disposition. When that disposition is configured to schedule a follow-up callback, a new row appears in the Scheduled callbacks panel with its due time — the next cycle of the same lifecycle, this time on the caller’s clock, not on FIFO.