> ## 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.

# Auto-schedule callbacks from wrap-up dispositions

> Define per-queue rules that turn an agent's wrap-up disposition into a scheduled, deduplicated callback request: delay windows, caller-ID override, recipient resolution, failure behavior, and auditing in the callback console.

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](/guides/voice-callback-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:

```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/queues/queue_01HZ.../disposition-callback-rules" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dispositionCode": "no-answer",
    "delayMinutes": 120,
    "callbackFromE164": "+15551234567"
  }'
```

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:

```bash cURL theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/queues/queue_01HZ.../disposition-callback-rules" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```bash cURL theme={null}
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/queues/queue_01HZ.../disposition-callback-rules/rule_01HZ..." \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'
```

* **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](/guides/voice-callback-console) for the console walkthrough and [Queue SLA forecast-callback runbook](/guides/queue-sla-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

| Wrap-up slug | `delayMinutes` | Result |
| - | - | - |
| `no-answer` | `120` | The caller is re-dialed two hours after the missed call, during the same business day. |
| `decision-maker-absent` | `1440` | A next-day follow-up for B2B queues where the contact asked to be called back tomorrow. |
| `call-back-next-quarter` | `40320` | The longest window the platform allows (28 days). For quarter-scale horizons, set the cap and re-book from the console when it comes due, or capture a caller-chosen date with [public queue self-booking](/guides/queue-appointment-booking). |
| `call-back-after-renewal` | `20160` | A two-week window for B2B renewals: re-engage shortly after the renewal date lands. |

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.

## Consent, quiet hours, and suppression

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](/guides/quiet-hours-configuration) and [TCPA posture across SMS and voice](/guides/tcpa-quiet-hours-and-windows).

## See also

* [Define and use disposition tags](/guides/voice-disposition-tags) — the per-call outcome taxonomy that sits next to wrap-up codes
* [Voice callback queue console](/guides/voice-callback-console) — the operator surface every scheduled callback lands in
* [Public queue self-booking](/guides/queue-appointment-booking) — caller-chosen callback times for horizons beyond the 28-day cap
* [Queue SLA forecast-callback runbook](/guides/queue-sla-callback-runbook) — forecasting and breach response behind the same queues


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.