> ## 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 Abandoned-Call Safe Harbor
> Configure the FCC § 64.1200(a)(7) abandoned-call identification message on your predictive-dialer campaigns — the per-campaign safe_harbor object, org-level fallback fields, the message template (business name, opt-out number, override, pre-recorded audio), the safe-harbor audit events, and a worked setup walkthrough.
# Dialer Abandoned-Call Safe Harbor
When a predictive dialer abandons an answered call — the recipient
picked up but no agent was connected within two seconds of the
completed greeting — the FCC grants a **safe harbor** only if the call
gets a prerecorded identification message before it is disconnected.
This page shows you how to configure that message: per campaign, with
an organization-level fallback, as text-to-speech or a pre-recorded
audio file.
## What the FCC requires
Under 47 C.F.R. § 64.1200(a)(7), a call placed by a predictive dialer
counts as compliant only when all of the following hold:
* **Abandonment stays at or below 3 %** per campaign, measured per day
over a 30-day window (a one-day allowance is built in for an
unavoidable spike).
* **The abandoned call is disconnected within two seconds** of the
called person's completed greeting. An answered call that sits
unanswered for two seconds is "abandoned" for the rule's purposes —
it does not require a live hang-up.
* **Each abandoned call plays a prerecorded identification message
before disconnection** that:
1. states the **name** of the business or entity on whose behalf the
call was placed (§ 64.1200(a)(7)(i)(B)), and
2. provides a **telephone number** the called party can use to make a
do-not-call request — for the automated mechanism this must be a
**toll-free number** (§ 64.1200(a)(7)(ii)).
Devotel Orbit enforces the 3 % ceiling for you: `max_abandon_rate` on a
campaign cannot be set above 0.03, and pacing throttles when the
ceiling trips. The identification message, though, is **your
configuration**. If you set nothing, an abandoned call receives a bare
hang-up — the safe harbor is unavailable, and every abandoned call is a
statutory TCPA/FCC exposure of $500–$1,500 per call.
This page documents tenant-owned configuration. It is **not legal
advice**, and Devotel Orbit does not guarantee your compliance — the
controls are tenant-owned, and whether your operations stay inside
the safe harbor is your responsibility. Confirm your posture with
qualified counsel.
## Where to configure
The message is configured per campaign on the
`dialer_campaigns.metadata.safe_harbor` object. Set it on create or
update via the campaign endpoints
(`POST /api/v1/dialer/campaigns` or
`PATCH /api/v1/dialer/campaigns/:id`) in the `metadata` field — no
schema migration or platform flag is involved:
```json theme={null}
{
"metadata": {
"safe_harbor": {
"enabled": true,
"business_name": "Acme Home Services",
"opt_out_number": "+18005551212",
"message": "...full override...",
"audio_url": "https://.../safe-harbor.wav"
}
}
}
```
Behaviour of the resolver:
* When the `safe_harbor` object is **present**, `enabled` **defaults to
true** — having configured it is the opt-in. An explicit
`"enabled": false` suppresses the message for that campaign.
* When no `safe_harbor` object exists, the campaign behaves exactly as
before: no disclosure is played, and the abandoned leg simply hangs
up.
* `business_name`, `opt_out_number`, `message`, and `audio_url` may
each be set or omitted; the field semantics are in the next section.
* Configuration lookups are read-only and best-effort: if the campaign
or organization record cannot be read, the call still completes —
with no disclosure — rather than failing.
### Organization-level fallback
To avoid repeating the shared business identity on every campaign, two
fields fall back to your **organization settings**. Add these to your
org profile and leave them off individual campaigns:
* `business_name`, `legal_business_name`, or `company_name` — checked
in that order — supply the identification name.
* `dnc_opt_out_number` or `opt_out_number` — checked in that order —
supply the do-not-call line.
Campaign-level values take precedence; the org fallback fills only what
the campaign does not set.
## Message template fields
| Field | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Optional. Defaults to `true` once the object exists; set `false` to silence the message for one campaign. |
| `business_name` | The entity on whose behalf the call is placed — the (a)(7)(i)(B) identification element. Falls back to org `business_name`, `legal_business_name`, `company_name`. |
| `opt_out_number` | The toll-free do-not-call line — use a number recipients can use to place a do-not-call request. Falls back to org `dnc_opt_out_number`, `opt_out_number`. |
| `message` | Optional full-text override. Wins over the composed template; capped at 500 characters. |
| `audio_url` | Optional pre-recorded file on an `https://` (or `http://`) URL. When set, the file plays instead of synthesized speech. |
Two rules decide what actually plays:
1. **Precedence.** An `audio_url` beats the `message` override, which
beats the composed template. In audio mode both the name and the
opt-out line are whatever your recording states — the system won't
inject them.
2. **Completeness.** The composed template is emitted only when
**both** a business name and an opt-out number resolve. If either is
missing and no override or audio URL supplies a full message, no
partial disclosure plays — the leg falls back to a bare hang-up. A
partial message would consume two seconds of greeting time without
closing the (a)(7)(i)(B) elements.
The default template text reads:
> "This call was made on behalf of **{business_name}**. We are sorry we
> are unable to connect you with a representative at this time. To be
> placed on our do-not-call list, please call **{opt_out_number}**."
## Audit trail
Every abandoned call produces a structured event you can query, plus a
counter. Filter your logs on the `event` field:
| Event | When it fires | Key fields |
| --------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `dialer_call_abandoned` | An attempt row is marked abandoned | `attemptId`, `campaignId`, `callSid`, `durationSeconds` |
| `dialer_safe_harbor_message` | The identification message played on the abandoned leg | `mode` (`tts` or `audio`), `businessName`, `optOutNumber`, `messageChars`, `audioUrl` |
| `dialer_safe_harbor_unconfigured` | The campaign had no compliant message resolved | `attemptId`, `callSid` |
For the safe-harbor audit you want `dialer_safe_harbor_message`: it
records the resolved business name and opt-out number the recipient
heard, alongside the attempt and call identifiers. A rising
`dialer_safe_harbor_unconfigured` count means campaigns are abandoning
calls with no disclosure — treat that as an exposure until fixed.
## Worked example: one campaign, one org fallback
1. **Set the org fallback once.** On your organization settings, add a
business identity and a toll-free do-not-call line, e.g.
`business_name: "Acme Home Services"` and
`dnc_opt_out_number: "+18005551212"`. Campaigns that omit both
fields inherit this pair.
2. **Enable safe harbor on one campaign.** Update the campaign with the
disclosure config:
```json theme={null}
{
"metadata": {
"safe_harbor": {
"enabled": true,
"message": "This call was made on behalf of Acme Home Services. To be placed on our do-not-call list, call 1-800-555-1212."
}
}
}
```
The explicit `message` removes any dependency on template fields
resolving.
3. **Verify configuration took effect.** The next time the campaign
abandons an answered call, the recipient hears your override before
disconnect, and your logs gain a `dialer_safe_harbor_message` entry
with `mode: tts`. Before any abandonment occurs, you can also sanity-
check pacing: with configuration in place your
`dialer_safe_harbor_unconfigured` event count stops climbing.
## Troubleshooting
| Symptom | Cause | Fix |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dialer_safe_harbor_unconfigured` events on abandoned calls | No `safe_harbor` object on the campaign, or `"enabled": false` | Add the object via `PATCH /api/v1/dialer/campaigns/:id` (omit `enabled` — presence enables it). |
| Abandoned calls still hang up silently even though `safe_harbor` is set | The composed template never forms because the business name or opt-out number failed to resolve, and no override or audio URL supplies a complete message | Set `business_name` **and** `opt_out_number` on the campaign, or on the org fallback (`business_name` / `dnc_opt_out_number`) — or set a `message` override / `audio_url`. |
| You set `audio_url` but recipients hear TTS | The URL did not start with `http://` or `https://` | Use an absolute URL scheme; anything else is dropped and the resolver moves to text mode. |
| Message text reads cut off | The `message` override exceeded 500 characters | Shorten the override; the cap mirrors other announcement-tier message limits. |
| No `dialer_safe_harbor_message` events, but also no `dialer_call_abandoned` events | The abandonment detector never flagged the call — the safe-harbor resolver only runs on an abandoned attempt | Investigate why abandonment is not being detected (pacing/agent-connect timing); the disclosure only plays on an attempt recorded as abandoned. |
The 3 % abandonment ceiling is a separate, always-on guard. It
throttles pacing, but it does not substitute for the identification
message — both halves of (a)(7) must hold for the safe harbor to be
available.
## See also
* [TCPA federal voice guard](/concepts/tcpa-federal-voice-guard) — the
one platform-global dialing-window check, distinct from every
tenant-owned control
* [Voice Guard: the federal dialing-window check](/compliance/voice-guard)
— the dispatch-time enforcement of that window
* [RND scrub](/compliance/rnd-scrub) — a different FCC safe harbor, for
reassigned numbers
* [Opt-out suppression](/compliance/opt-out-suppression) — where the
do-not-call line feeds into your suppression lists