Skip to main content
When an agent wraps a call as no-answer or “call back next quarter”, the follow-up usually lives in agent memory or an external sheet. Disposition-callback rules move that follow-up into the platform: you define one rule per queue and wrap-up code, and every matching wrap-up queues a callback request automatically, due at the time offset you choose. The agent keeps wrapping calls exactly as before; the rebooking happens on its own. This guide covers why rules beat manual rebooking, how to create and manage a rule, how the recipient number is resolved, dedup and attempt semantics, auditing scheduled callbacks in the console, worked recipes, and how every failure path behaves. Base path: /api/v1/voice/queues/{queueId}/disposition-callback-rules Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: voice:write plus an owner, admin, or developer role.

​
1. Why automatic callback rules beat manual rebooking

A rule turns every missed outcome into open work the platform owns:
  • Every outcome becomes a scheduled row. A wrap-up of no-answer, decision-maker-absent, or call-back-after-renewal creates a callback request with a due time, instead of a note that only exists while the agent remembers it.
  • Follow-ups are bounded, not open-ended. Each request joins the queue’s callback list in due-time order and gets a capped attempt ladder of three dial attempts, so a follow-up neither sits forever nor over-dials the caller.
  • Retries are deduplicated. Wrapping the same call a second time does not queue a second callback for it, so agents can correct a wrap-up without doubling the caller’s expected calls.
  • Nothing depends on end-of-shift discipline. The rule fires as part of the wrap-up itself, on every call, including the ones wrapped in a rush between rings.
Rules complement the manual surfaces rather than replacing them: callers who opt into a callback from the overflow IVR still land in the same console, and operators can still create, retry, and cancel requests by hand. See Voice callback queue console for the operator side.

​
2. Define a rule

A rule binds three things: the queue, the wrap-up slug, and the delay window in minutes. Creating one takes a single POST:
cURL
Body fields:
  • dispositionCode (required) — the wrap-up slug exactly as your agents record it at wrap-up: lowercase letters, digits, _ or -, max 60 characters. The rule matches on the recorded code string, so use the same slug your queue’s disposition picker posts.
  • delayMinutes (optional, default 60) — how many minutes after the wrap-up the callback becomes due. Bounded 1 to 40,320 (28 days).
  • callbackFromE164 (optional) — the outbound caller ID these callbacks present, in E.164. Omit it to inherit the queue’s default caller ID.
Create returns 201 with the stored rule. A 409 means an active rule already exists for this queue and slug: update it with PATCH instead of creating a second one. Manage rules per queue:
cURL
cURL
  • Retire with isActive: false rather than deleting. The row stays in the list so you can reactivate it, and historical auditing stays intact. An inactive rule simply stops enqueueing.
  • Retime with delayMinutes and swap the caller ID with callbackFromE164 (send null to revert to the queue default). Both take effect from the next wrap-up; the rule is re-read on every disposition, so there is no cache to wait out.
  • To change which wrap-up code a rule fires on, retire the old rule and create a new one. Keeping one rule per slug keeps the audit trail readable, and the retire-then-create flow matches how the wrap-up catalog itself is curated.

​
3. How recipient resolution works

The callback dials the external number of the original inbound call: the caller’s number as the carrier delivered it on the call record the agent just wrapped. Resolution matches the wrapped call by its call id or the provider call id, the same way the dispatcher resolves recipients at dial time. Two consequences follow:
  • You never store or re-type the caller’s number; the rule only says when to call back, and the platform takes whom from the inbound record.
  • If the wrapped call has no resolvable inbound number (a legacy or malformed call reference), the enqueue is skipped and the wrap-up still succeeds. See section 7.

​
4. Priority and dedup semantics

  • One auto-callback per original call. The queue holds at most one pending auto-scheduled callback per original call, so an agent who re-wraps a call, or two agents correcting the same wrap-up, cannot double-book the caller. The second wrap-up is a no-op for the callback.
  • Due-time ordering. A request becomes due at wrap-up time plus delayMinutes, and the dispatcher works the queue’s callbacks in due-time order alongside virtual-hold and operator-created requests.
  • Capped attempts. Each request gets up to three dial attempts before it settles into a terminal status, the same ladder the console documents.
  • Rules are queue-scoped. A rule created on one queue never fires for wrap-ups on another queue, and each queue’s list shows only that queue’s rules.

​
5. Audit scheduled callbacks in the console

Every auto-scheduled request appears under Scheduled callbacks at Voice → Callbacks, carrying its due time and flagging any request whose window lapsed while still pending. From the same console you filter by queue and status, pull a pending attempt forward with Retry now, or cancel a request outright, exactly as you would for a virtual-hold callback. The status vocabulary (Pending, Dialing, Connected, Failed, Abandoned, Canceled) is shared, so reporting and operator habit carry over unchanged. See Voice callback queue console for the console walkthrough and Queue SLA forecast-callback runbook for forecasting behind the same queues. On the rule side, the GET list from section 2 is your audit surface for configuration: which slugs enqueue on each queue, their current delay window and caller ID, and which rows are retired.

​
6. Worked recipes

Keep the slugs in sync with what your agents actually pick: the rule matches the recorded code string, so a rule for no-answer never fires for a wrap-up recorded as no_answer.

​
7. Failure modes: the wrap-up never fails because of a rule

Enqueueing is deliberately additive. In every case below, the agent’s wrap-up completes normally and the agent returns to available; only the callback side changes.
  • No matching rule. A wrap-up code with no active rule on that queue enqueues nothing. Rules are opt-in per queue and per slug.
  • Inactive rule. A retired rule (isActive: false) enqueues nothing until reactivated.
  • Recipient not resolvable. If the inbound number cannot be resolved from the wrapped call, the enqueue is skipped. The rule side still lists normally, so you can confirm the rule exists and treat the missing row as a resolution skip.
  • Repeat wrap-up on the same call. Deduplicated per section 4; the caller keeps a single pending callback.
  • Reading rules through a different queue’s path. Each queue’s list shows only that queue’s rules, so a rule never leaks across queues.
  • Database unavailability at wrap-up time. The enqueue is skipped and logged; the wrap-up result the agent sees is unchanged.
An auto-scheduled callback is still an outbound call to a person, and it obeys the same tenant-owned posture as every other callback: your quiet hours and calling windows gate when attempts may place, and suppression and opt-out lists apply at dispatch. A rule never dials through a suppression entry or outside your configured windows; a request whose window lapses while suppressed surfaces as lapsed in the console rather than dialing late. Review your posture in Quiet hours configuration and TCPA posture across SMS and voice.

​
See also