​

Ruhezeiten: organisationsweite Kanal-Gates vs. das Kampagnen-Fallback-Fenster

1. Das organisationsweite Kanal-Gate — Kanalschalter in den Organisationseinstellungen (settings → quiet_hours.<channel>.enabled), geschrieben über PUT /api/v1/settings/general und gespiegelt in den Organisationseinstellungen des Dashboards (siehe auch Compliance-Haltung).
2. Das Kampagnen-Fallback-Fenster — ein einzelnes organisationsweites Start/Ende-Paar für Drip- und Journey-Sendungen, deren Kampagnenzeile kein eigenes Fenster trägt. Im Dashboard: Einstellungen → Kampagnenlimits → Standard-Ruhezeiten; über die API: GET/PUT /api/v1/campaigns/quiet-hours/settings.
3. Der Vorschau-Endpunkt — GET /api/v1/compliance/quiet-hours/preview, eine schreibgeschützte Prüfung, die beantwortet: „Würde diese Sendung an diesen Empfänger jetzt durchgehen?” Führen Sie sie vor jeder Einführung aus; sie wird im Runbook unten durchgespielt.

​

Die zwei Fenster

​

Organisationsweites Kanal-Gate pro Kanal

​

Standardhaltung pro Kanal

​

Zwei Ausnahmen, die wesentlichen Verkehr fließen lassen

• Vorherige ausdrückliche Einwilligung — mit consent_overrides_quiet_hours auf true (Standard) passiert ein Empfänger mit ausdrücklichem Einwilligungsnachweis auf jedem Nicht-Voice-Kanal. Voice nimmt diese Ausnahme nie in Anspruch.
• Transaktionale Verkehrsspur — Sendungen, die der Aufrufer als transaktional kennzeichnet (OTPs, Alarme, Kontobenachrichtigungen), sind vom Gate ausgenommen, selbst auf einem aktivierten Kanal. Voice nimmt auch diese Ausnahme nie in Anspruch.

​

Kampagnen-Fallback-Fenster

curl https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "enabled": false,
  "start_hour": null,
  "end_hour": null,
  "platform_default_start": 21,
  "platform_default_end": 9
}

curl -X PUT https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "start_hour": 22, "end_hour": 7 }'

curl -X PUT https://api.orbit.devotel.io/api/v1/campaigns/quiet-hours/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

​

Auflösung der Empfänger-Zeitzone

1. Ein expliziter recipientTimezone-Hinweis des Aufrufers, sofern angegeben.
2. US-Vorwahl → IANA-Zeitzone, für +1-Nummern.
3. E.164-Ländercode → eine repräsentative IANA-Zeitzone (Europa, Asien, die Amerikas und übliche Betreibermärkte).
4. Für E-Mail-Empfänger die Standard-Zeitzone der Organisation.
5. Wenn nichts davon auflöst — die unknown_timezone_policy der Organisation (im Dashboard ebenfalls konfigurierbar unter Einstellungen → Voice):

​

TCPA-Bundes-Voice-Ausnahme

​

Einwilligung überschreibt Ruhezeiten

​

Mini-TCPA-Overlays der Bundesstaaten

• outside_state_window — ein Bundesstaat-Overlay hat das Fenster verschärft, und diese Stunde lag außerhalb.
• state_blocked_day — das Overlay verbietet das Wählen an diesem Wochentag vollständig.

​

Operationales Runbook

1. Eine Stichprobe von Empfängern mit GET /api/v1/compliance/quiet-hours/preview?phone=<E.164>&channel=<channel> vorschaubar prüfen; timezone_override=<IANA> nur hinzufügen, wenn Ihr CRM einen besseren Hinweis liefert als die Nummer auflöst.
2. Den Organisations-Gate-Block bestätigen: GET /api/v1/settings/general aufrufen und den quiet_hours-Baum vor dem PUT lesen — Schreibvorgänge mergen auf der obersten Ebene, aber der quiet_hours-Schlüssel selbst wird vollständig ersetzt (siehe den Schreibabschnitt unten).
3. Bei Massen-Einführungen GET /api/v1/settings/compliance-health im Blick behalten — dessen Warnungen rängen den schlimmsten Verursacher (am häufigsten zurückgehaltener Absender, Fehlercluster) zuerst, damit Sie die lautesten Spur zuerst fixen.

​

Durchgespielte Beispiele

​

Massen-einführung um 21:05 — Verhalten der Halte-Queue

• In-Fenster-Empfänger geben sofort zugelassen.
• Zurückgehaltene Empfänger bekommen einen 422 mit next_allowed_at; Ihr Worker parkt sie und setzt den Batch fort. Der Batch selbst pausiert nicht — Halte sind pro Empfänger.
• Wenn das Fenster jedes Empfängers wieder öffnet, reichen Sie die geparkte Zeile erneut ein; während der Haltezeit wurde kein Slot verbrannt.

curl "https://api.orbit.devotel.io/api/v1/compliance/quiet-hours/preview?phone=%2B14155551234&channel=sms" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

{
  "allowed_now": false,
  "local_hour": 21,
  "local_timezone": "America/New_York",
  "window_start_local": "08:00",
  "window_end_local": "21:00",
  "next_allowed_at": "2026-08-26T12:00:00Z",
  "reason": "outside_window",
  "channel": "sms"
}

​

Zeituneaufgelöster US-Voice-Empfänger — fail-closed

​

Einwilligungs-Override innerhalb des Fensters

Kontakt a — Einwilligungsnachweis vorhanden  → zugelassen (Grund: consent_override)
Kontakt b — kein Einwilligungsnachweis      → zurückgehalten (422 QUIET_HOURS_BLOCKED)

​

Einen Kanal über die Organisationseinstellungen-API aktivieren

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/general \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "quiet_hours": {
        "sms": { "enabled": true },
        "whatsapp": { "enabled": true, "start_hour": 9, "end_hour": 21 },
        "unknown_timezone_policy": "skip",
        "consent_overrides_quiet_hours": true
      }
    }
  }'

​

Eine Haltung wählen

1. Alles aus lassen (Standard), wenn Sie außerhalb von Ruhezeiten-Jurisdiktionen operieren oder Grenzen woanders behandeln. Ein Vorbehalt: US-Kampagnen- und Dialer-Voice bleibt hart blockiert — das lässt sich nicht ausschalten.
2. US-Marketing-Betreiber — aktivieren Sie sms (und Voice, wenn Sie ad-hoc wählen) auf dem Organisations-Gate; die Plattform-Stunden 08:00–21:00 Empfänger-Ortszeit gelten sofort. Die Einwilligungsausnahme hält erlaubte Empfänger erreichbar.
3. EU/APAC-Betreiber mit Drip-Kampagnen — setzen Sie das Kampagnen-Fallback auf Ihr lokales Fenster (z. B. 22:00 → 07:00) unter Einstellungen → Kampagnenlimits, damit jede Drip und Journey ohne eigenes Fenster in Ihrem Regime sendet. Fügen Sie das Organisations- Gate pro Kanal hinzu, wenn Sie auch 1:1-Verkehr zurückhalten wollen.

​

Siehe auch

• Send-Gates — der Vorschau-Endpunkt und der vollständige Gate-Stapel (DNC, RND, Notfall-Stopp).
• US-Bundesstaat-Anruffenster — welche Bundesstaaten ein strengeres Mini-TCPA-Overlay tragen und wie der Block zu einer Statute zurückverfolgt.
• API-Referenz → Compliance — vollständige Anfrage-/Antwort-Schemas.
• Kampagnen-A/B-Tests — wie Gewinner-Auswahl und Hold-Out-Experimente durch dieses Gate und pro-Kontakt-Frequenzlimits laufen.