​

Preference Center: die öffentliche Opt-in/Opt-out-Seite

Englisches Original: Preference center: the public opt-in/opt-out page.

​

1. Einmal konfigurieren: POST/GET /preference-center

​

Konfigurationsfelder

​

Abonnement-Themen

• name (1–120 Zeichen) — der auf der Seite angezeigte Name.
• description (optional, ≤500) — eine Zeile Kontext neben der Kachel.
• defaultOptIn (Standard false) — wie ein Kontakt ohne aufgezeichnete Präferenz behandelt wird.
• archived (optional) — archivierte Themen bleiben im Audit-Trail, erscheinen aber nicht mehr auf der Seite.

​

2. Pro-Kontakt-Link erstellen

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cnt_01H…" }'

• Der Link zielt auf die gehostete Seite, nicht auf das JSON-Endpunkt. Kopieren Sie ihn wörtlich in Ihre Fußzeilen-/Absender-Vorlagen; die Seite selbst ruft den Daten-Endpunkt unter der Haube ab.
• 30-Tage-TTL. Danach wird das Token als abgelaufen geprüft und der Kontakt muss einen neuen Link anfordern (das Erstellen eines neuen erfordert einen API-Aufruf).
• Die Seite ist zum Erstellungszeitpunkt sprachagnostic. Die Web-App löst eine Umleitung unter Beibehaltung der ?token=-Abfrage, sodass Sie das Locale des Kontakts nicht erraten müssen.

​

Wo er platziert wird

• E-Mail-Fußzeile (primär). Hängen Sie den generierten Link (oder die kurze, verfolgte Variante, die Ihr Mailer verwendet) in den Abmeldebereich der Marketingvorlagen an.
• SMS / WhatsApp-Fallback. Wenn die Nachricht keinen Fußzeilenblock hat, hängen Sie den Link inline an: {optOutMessage}: {link}. Der Helfer, der ausgehende Körper erstellt, akzeptiert einen vorab erstellten Kurzlink, sodass Ihr Abmeldeklick weiterhin die normale Klick-Attribution erhält.
• Suppression-getriebener Wieder-Opt-in. Wenn ein Kontakt über einen anderen Ablauf wieder opt-int, können Sie ihm einen frischen Link geben, damit er dieselbe Self-Service-Seite erhält.

​

3. Die öffentliche Token-Seite

• GET /preferences/:token — gibt die Seiten-Ladung zurück.
• PUT /preferences/:token — wendet Aktualisierungen an.

​

GET-Antwort

{
  "contactId": "cnt_01H…",
  "displayName": "…",
  "email": "m*****@example.com",
  "phone": "+15551****…",
  "channelPreferences": { "sms": "opted_in", "email": "opted_out" },
  "frequencyPreference": "all",
  "channels": ["sms", "email"],
  "topics": [ { "id": "newsletter", "name": "Newsletter", "defaultOptIn": false } ],
  "topicPreferences": { "newsletter": "opted_in" },
  "consentHistory": [
    { "channel": "all", "state": "opted_out", "topicId": "newsletter", "occurredAt": "2026-09-01T…" }
  ],
  "config": { /* die Konfiguration der Organisation */ }
}

​

PUT-Anfragetext

{
  "channelPreferences": {
    "sms": "opted_in",
    "email": "opted_out"
  },
  "frequencyPreference": "important_only",
  "topicPreferences": { "newsletter": "opted_in" },
  "requestDataDeletion": false
}

• channelPreferences — Teilabbildung erlaubt (Zod-Partial-Record); mindestens ein Kanal erforderlich.
• frequencyPreference — optional, einer von all, important_only, weekly_digest, monthly_digest.
• topicPreferences — optional { topicId: opted_in | opted_out } Abbildung, validiert gegen Ihre konfigurierten Themen; unbekannte IDs werden ignoriert.
• requestDataDeletion — setzt neben dem Opt-out einen GDPR-Löschungsantrag (siehe Abschnitt 6).

​

4. Wie Aktualisierungen fließen

• Einwilligungsledger. Eine consent_records-Zeile pro Kanal (oder pro Thema) wird mit source: preference_center angehängt — Ihr GDPR-Artikel-7-Beweislast-Audit-Trail.
• Suppression-Liste. Auf jedem abgemeldeten Kanal wird die kanonischierte Telefon/E-Mail des Kontakts mit Scope all eingefügt — eine kanalübergreifende Sperre, die jedes Send-Gate liest.
• STOP-Zaun. Bei Opt-out wird ein Redis-Schnellpfad-Zaun gesetzt (und bei vollständigem Wieder-Opt-in gelöscht), sodass in-flight-Kampagnen-Batches die Änderung vor der langsameren Datenbank-Suppression-Propagation sehen.
• Audit-Log. compliance.preference_center_updated wird aufgezeichnet, wenn Sie die Konfiguration ändern, und Kontakt-Level-Opt-in/out-Ereignisse werden im Einwilligungsledger erfasst.

​

5. GDPR-Lösch-Kachel-Semantik

​

6. Testen

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Logistics",
    "primaryColor": "#1d4ed8",
    "channels": ["sms", "email"],
    "headerText": "Manage how Acme contacts you",
    "topics": [
      { "id": "shipping-updates", "name": "Shipping updates", "defaultOptIn": true },
      { "id": "promotions", "name": "Promotions", "defaultOptIn": false }
    ]
  }'

LINK=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"cnt_01H…"}' | jq -r '.link')

TOKEN="${LINK#*token=}"

curl -s "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" | jq

curl -s -X PUT "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelPreferences":{"sms":"opted_out"}}' | jq

​

Verwandt

• Send Gates und Pre-Send-Schutz — wo die Preference-Center-Zusammenfassung neben Ruhezeiten, Notfall-Stopp und Drosseln lebt.
• Opt-Out & Suppression-Listen — wie Scope all und Bulk-CSV-Importe mit dieser Oberfläche zusammenhängen.
• Einwilligungsverwaltung — die Operator-seitige API, die dasselbe Einwilligungsledger speichert.
• DSAR-Referenz — die verfolgte Löschpipeline, zu der requestDataDeletion-Anträge geroutet werden.