Quiet Hours FAQ: Org Gate vs. Campaign Fallback vs. Preview
Operators hit the troubleshooting pages
TCPA window blocked calls and
voice window sentinel breadcrumbs
one issue at a time. This page consolidates the questions that generate
that volume. Read this first; run the runbook at the bottom when a send is
already blocked.
The deep runbook lives in
Quiet hours: org gates vs. the campaign fallback.
This page answers; that page explains.
The three surfaces
Three surfaces compose your quiet-hours posture, and confusing them is the
source of nearly every “why was this held?” ticket:
- The org-wide channel gate — per-channel toggles written through
PATCH /api/v1/settings/compliance/quiet-hours. This gates every send
on an enabled channel: dashboard, API, flows, and campaign dispatch
alike. All channels ship off; a flips-on posture is additive.
- The campaign fallback window — a single org-wide start/end pair for
drip and journey sends whose campaign row carries no explicit window.
In the dashboard: Settings → Campaign limits → Default quiet hours;
over the API:
GET/PUT /api/v1/campaigns/quiet-hours/settings.
- The preview endpoint —
GET /api/v1/compliance/quiet-hours/preview,
a read-only answer to “would this send to this recipient go through
right now?” Its channel-by-channel semantics are mapped on
Quiet-Hours Preview.
Which layer answers first?
None of them “answers first” — the org gate and the campaign path are
separate layers, both evaluated at the send site:
- 1:1 and ad-hoc traffic (dashboard send, API call, flow step): only
the org channel gate applies, and only for channels you have enabled.
- Campaign / drip / journey traffic: the campaign-path window resolves
first — the campaign row’s own
quiet_hours_start / quiet_hours_end,
then the org fallback window, then the platform default 21:00 → 09:00
recipient-local. If you have also enabled that channel on the org gate,
the send must clear both layers.
Either layer can only narrow the envelope, never widen it. The
full layering table is in
Quiet hours configuration.
Is the org-wide gate or the campaign fallback blocking my send?
The most-asked question, per troubleshooting volume. Read the
organization → settings → quiet_hours document and the campaign
fallback window together:
- A 1:1 send that was held is always the org channel gate — the
fallback window never touches ad-hoc traffic.
- A campaign send that was held is whichever layer failed: the
campaign row window, or the fallback, or the platform default —
plus the org gate when that channel is enabled.
- The
422 QUIET_HOURS_BLOCKED voice variant TCPA_DIALING_WINDOW_BLOCKED
or preview reason tells you which window closed; the dashboard readback
(GET the settings document with jq on the resolved map, as in the
runbook)
shows you why.
When in doubt, preview the recipient before blaming a layer:
GET /api/v1/compliance/quiet-hours/preview?phone=<E.164>&channel=<channel>
returns the exact window and reason the send path would apply.
How is next_allowed_at computed?
next_allowed_at is the earliest UTC timestamp at which the resolving
recipient’s window reopens, computed recipient-local through the full
resolution chain (explicit recipientTimezone hint, US area code, E.164
country code, org default for email, else the org’s
unknown_timezone_policy). It is a DST-safe ISO timestamp — pass it
straight to your scheduler instead of retrying in a loop.
For a layering of multiple windows (campaign window + org gate), the
timestamp is the first instant both layers admit. Holds are
per-recipient and burn no quota, so re-submitting at next_allowed_at
re-admits cleanly. The exact payload shape is on
Quiet-Hours Preview.
Where do DST cutovers land?
The gate evaluates recipient-local wall time, so a DST transition shifts
when your window opens relative to UTC — not relative to the recipient’s
clock. The crossover-night runbook (Arizona, Hawaii, ambiguous windows)
lives in Quiet hours across DST.
Run the preview endpoint against a sample of recipients before the
spring-forward and fall-back weekends and confirm the resolved
local_timezone on the response.
For USPS-recipient voice the hold never resolves to a timezone: the
federal window blocks fail-closed with 422 TCPA_TIMEZONE_UNKNOWN — DST
never comes into it. For non-voice channels the org’s
unknown_timezone_policy (skip default / enforce_utc / deny)
decides; see the resolution chain above and
Number timezone and state resolution.
Do state mini-TCPA overlays touch the same layers?
Yes — state overlays (Florida’s Sunday ban, Oklahoma/Mississippi windows,
and the rest) compose on top of whichever layers carry the send, as
most-restrictive-wins. A campaign voice send must clear the federal
window, the campaign-path window, the org gate (if the voice channel is
enabled), and every applicable state overlay. Voice blocks report
outside_state_window or state_blocked_day so a state hold is
separable from a federal one. The state-by-state table is on
US calling windows: federal TCPA + state overlays,
with the posture composition in
TCPA posture guide.
Worked runbook: a blocked send carrying next_allowed_at
- Capture the hold: your worker receives
422 QUIET_HOURS_BLOCKED (or TCPA_DIALING_WINDOW_BLOCKED on voice)
and reads next_allowed_at out of the error details.
- Identify the layer: compare the error’s
window_start_local /
window_end_local against your stored org document
(GET /api/v1/settings/compliance/quiet-hours) and the campaign
fallback (GET /api/v1/campaigns/quiet-hours/settings) — the values
match exactly one of the stored windows.
- Park the recipient: schedule the retry for
next_allowed_at; do not
burn attempts polling. Holds consume no quota and no slot reservation.
- Reverify before rollout-scale sends: preview a sample through
GET /compliance/quiet-hours/preview, one per distinct timezone in
the list, and confirm allowed_now: true.
- If the window is wrong: decide which layer owns the correction —
the campaign row, the fallback, or the org gate — and fix it there.
Writes propagate to every send site within about a minute, then reads
confirm immediately.
FAQ
I enabled the org gate on sms — do my drip campaigns inherit it?
They clear it as a separate layer, plus the campaign-path window. The
fallback (Settings → Campaign limits → Default quiet hours) still
applies to any campaign without its own window; the org gate adds the
ad-hoc-style hold on the same channel. Tighten at either layer; the two
compose most-restrictive-wins.
Can the fallback window relax the org gate?
No. Fallbacks narrow the envelope, never widen it. The same asymmetry
applies to the consent carve-out: consent_overrides_quiet_hours relaxes
non-voice channels only, and voice ignores the flag entirely.
Why did a blocked send say the window was the platform default when I
set a fallback?
PATH resolution order is campaign row → fallback → platform default.
A campaign with its own empty quiet_hours_start uses the fallback; if
your GET on the fallback reads enabled: false, the platform default
21:00 → 09:00 applies. Verify with
GET /api/v1/campaigns/quiet-hours/settings — it echoes
platform_default_start / platform_default_end so you see which regime
would actually apply.
Does the preview endpoint hold anything?
No — it is read-only, the same rule as the compliance-health scores. It
reports what the gate would do at this instant; run it freely in
pre-flight.
Is US campaign voice affected by any of these toggles?
No. Campaign and dialer voice to US recipients is hard-blocked outside
the federal 8 AM–9 PM recipient-local window with no tenant toggle, no
org gate required, and no consent carve-out. This is the one rail the
platform owns; everything else on this page is yours to configure.
Tenant-owned controls, not legal advice. Which laws apply to your
traffic depends on your jurisdiction, your recipients, and what you
send — confirm with qualified counsel before you rely on the wording
here.
See also
