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

# Dialer pacing: claim modes, enrollment ordering, best-time-to-dial, and the abandon ceiling

> How the outbound dialer sequences a contact list — the four claim modes, the next_attempt_at ordering that both claim paths share, best-time-to-dial enrollment, the FCC abandon-rate ceiling control, and how dispositions write back into the pacing engine.

# Dialer pacing and answering model

Every outbound dialer campaign answers three questions — *who* dials (claim mode), *when* each contact becomes eligible (enrollment ordering), and *how fast* the list can run (the abandon ceiling for predictive mode). This page documents each axis and the tenant-owned controls behind it. All outbound voice dials originate through the Devotel softswitch; the pacing model below governs when and how quickly those dials launch.

## The four claim modes

A campaign's `mode` decides which surface claims its contacts.

| Mode          | Who initiates the dial           | Surface                                                                                                                                                           |
| ------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preview`     | The agent, one contact at a time | Agents poll `GET /dialer/next-call`; each poll atomically claims the next eligible contact so two agents can never receive the same row.                          |
| `progressive` | The pacing scheduler             | Launches one dial per newly-idle agent per tick — a conservative 1:1 cadence with no abandon exposure.                                                            |
| `predictive`  | The pacing scheduler             | Launches `idle_agents × pacing_ratio` dials per tick across multiple lines. A self-adjusting ratio is throttled against the abandon ceiling (below).              |
| `agentless`   | The pacing scheduler             | Schedule-fires a fixed batch per tick regardless of agent presence, and routes the call to either a recorded broadcast message or your designated AI voice agent. |

`preview` is the only mode driven by the `GET /dialer/next-call` endpoint — for `progressive`, `predictive`, and `agentless` campaigns that endpoint returns `204 No Content`, and the pacing scheduler ticks every 30 seconds for the active campaigns on your tenant.

## Enrollment and ordering

Every contact row carries a `next_attempt_at` timestamp. Both claim paths — preview polls and the scheduler tick — order by `next_attempt_at ASC` and only pick up contacts whose timestamp has arrived. Upload ordering is therefore fully under your control:

* **Default.** List upload stamps `next_attempt_at = now()`, so the whole list is eligible immediately and the list dials top-to-bottom in upload order.
* **Scheduled.** Provide a specific `next_attempt_at` per contact at upload, or set one via a callback disposition, and the contact waits until that moment.
* **Best-time-to-dial (below).** Stamps each contact's predicted best window instead.

Retry logic writes back into the same ordering column: a failed attempt re-queues the contact at a backoff offset, and a `callback` disposition re-queues at the scheduled time.

## Best-time-to-dial

Set `best_time_to_dial: true` on campaign create or update (the value is stored in the campaign's `metadata`). Contacts uploaded to that campaign are stamped with their highest-answer-probability window from the engagement engine — the same engine that powers optimal send time for messaging, evaluated on the `voice` channel — instead of `now()`. The claim path still just reads `next_attempt_at`; no hot-path change.

Fallbacks chain in order:

1. **Cross-channel fallthrough.** A contact with no voice engagement history gets the engine's cross-channel aggregate (SMS or email history still yields a window).
2. **Local morning.** A contact with no engagement history at all gets a timezone-aware local-morning window, resolved from the number's area code where possible.
3. **Immediate.** If the engagement engine is unreachable, the upload fails open — every contact enrolls with `next_attempt_at = now()`. Enrollment never blocks on the optional optimizer.

The federal TCPA quiet-hours gate still evaluates every dial at dispatch time in the recipient's local time, so a predicted window can never push a dial outside the permitted calling window. See [TCPA federal voice guard](/concepts/tcpa-federal-voice-guard).

## The abandon ceiling

Predictive mode dials multiple lines per idle agent, which creates abandonment risk: a callee answers with no agent to take the call. The **abandon rate** is the fraction of connected calls abandoned; US federal rules cap predictive-dialer abandonment at **3% over a rolling 30-day window** (47 U.S.C. § 227 / 47 C.F.R. § 64.1200(a)(7)).

Two controls keep the campaign inside the ceiling. Both are **organization-level settings** — one value per account, not per campaign:

* **Default.** With no override configured, the pacer governs against the FCC 3% hard cap.
* **Override.** `GET` and `PUT /voice/dialer-abandon-ceiling` let you set a tighter ceiling (between 0.1% and the 3.0% FCC cap) as a percent — for example, pinning 2.5% for higher-quality lines. Clearing the override deletes the setting and the pacer falls back to the FCC default.

Semantic rules:

* The FCC 3% cap is a **ceiling control, not a compliance guarantee** — the pacer clamps anything stored above it, and the auto-abort below is the actual enforcement layer. Your own legal posture still owns consent and list hygiene.
* A **warning signal** fires when the observed rate climbs to 80% of the effective ceiling, before the hard abort engages.
* Within safe bounds, a self-adjusting **pacing ratio** eases up when the rate runs comfortably low and throttles when it approaches the ceiling, keeping throughput high without breaching the cap.

### Auto-abort enforcement

When the rolling 30-day abandon rate crosses the effective ceiling, the campaign flips to `status: "aborted"`. That state is terminal — no further dials launch, and the campaign can't be re-activated. Create a new campaign after reviewing the abort reason. The abort guard is the legally safe response; pacing adjustment alone is not relied on to recover a breach.

## How dispositions write back into pacing

The disposition an agent (or the dial-status webhook) submits decides whether and when the contact re-enters the pacing queue:

* **Terminal outcomes** — `connected` outcomes (`sale`, `no_sale`, `voicemail`, `interested`, `not_interested`), `wrong_number`, `dnc`, and carrier failures — close the contact out of pacing.
* **Callback** — `callback` / `callback_later` sets `next_attempt_at` to the scheduled time; pacing re-picks the contact then.
* **Retry** — failed attempts re-queue the contact at an increasing backoff until the per-contact `max_attempts` is consumed, at which point the contact is `exhausted`.
* **DNC** — a `dnc` disposition also writes the phone into your tenant-wide blocked list, so every campaign's pacing tick skips it from then on.

The full disposition-to-status matrix and the submission endpoint are documented in [Dialer dispositions](/voice/dialer-dispositions).

## See also

* [Dialer dispositions](/voice/dialer-dispositions) — the outcome → status matrix and submission endpoint
* [Voice API overview](/api-reference/dialer) — campaign create/update fields including `best_time_to_dial`
* [TCPA federal voice guard](/concepts/tcpa-federal-voice-guard) — the hard 8 AM–9 PM recipient-local window checked at dispatch
* [Consent and suppression model](/concepts/consent-and-suppression-model) — tenant-wide DNC lists and opt-out handling