​

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 Anzeigename auf der Seite.
• description (optional, ≤500) — eine Kontextzeile neben der Kachel.
• defaultOptIn (Standard false) — wie ein Kontakt ohne erfasste Präferenz behandelt wird.
• archived (optional) — archivierte Themen bleiben im Audit-Trail, rendern aber nicht mehr auf der Seite.

​

2. Einen Pro-Kontakt-Link prägen

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 den JSON-Endpunkt. Kopieren Sie ihn wortwörtlich in Ihre Footer-/Sender-Templates; die Seite selbst holt den Daten-Endpunkt unter der Haube.
• 30 Tage TTL. Danach verifiziert das Token als abgelaufen, und der Kontakt muss einen frischen Link anfordern (einen neuen zu prägen kostet einen API-Aufruf).
• Die Seite ist zur Prägezeit Locale-agnostisch. Die Web-App löst einen Redirect unter Beibehaltung der ?token=-Query auf, Sie müssen also das Locale des Kontakts nicht raten.

​

Wohin damit

• Marketing-Sendungen mit Freitext-Body: wird für Sie angehängt. Sie müssen den Link nicht platzieren. Orbit hängt während aktivem Preference Center an jede Marketing-Sendung mit Freitext-Body eine Zeile {optOutMessage}: {link} an — auf sms und whatsapp über Ihre gebrandete Kurzdomain, auf email und den übrigen Freitext-Kanälen als rohen tokenisierten Link — und Template-Sendungen werden übersprungen. Dieselbe Seite beschreibt, wann der Footer erscheint, was der angehängte Klick schreibt und wie er sich zur Carrier-Formulierung “Reply STOP” verhält: siehe Preference Center: when Orbit appends the opt-out footer for you.
• Transaktionale und Template-Sendungen: selbst platzieren. Diese Sendungen tragen den angehängten Footer nie, daher ist der oben geprägte Link ihr Weg zum Ein-Klick-Abmelden: kopieren Sie ihn wortwörtlich in den Abmeldebereich Ihrer E-Mail-Templates und dichten Sie ihn in Template-Texte oder transaktionale Bodys ein, wo Sie einen wollen. Für eine Platzierung einen kurzen getrackten Link zu prägen ist optional; schlägt die Kurzlink-Prägung fehl, funktioniert weiterhin der rohe Link — der Fallback ist additiv, nie tragend für Compliance.
• Suppressions-getriebenes Re-Opt-in. Wenn ein Kontakt durch einen anderen Flow wieder eintritt, können Sie ihm einen frischen Link geben, damit er dieselbe Self-Service-Seite erhält.

​

3. Die öffentliche Token-Seite

• GET /preferences/:token — liefert das Seiten-Payload.
• PUT /preferences/:token — wendet Updates an.

​

GET-Antwort

{
  "contactId": "cnt_01H…",
  "displayName": "…",
  "email": "m*****@example.com",      // masked
  "phone": "+15551****…",             // masked
  "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": { /* the org's preference-center config */ }
}

​

PUT-Request-Body

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

• channelPreferences — partielle Map erlaubt (Zod partial-record); mindestens ein Kanal ist erforderlich.
• frequencyPreference — optional, eines von all, important_only, weekly_digest, monthly_digest.
• topicPreferences — optionale { topicId: opted_in | opted_out }-Map, validiert gegen Ihre konfigurierten Themen; unbekannte Ids werden ignoriert.
• requestDataDeletion — setzt einen GDPR-Löschantrag parallel zum Opt-out (siehe Abschnitt 6).

​

4. Wie Updates fließen

• Consent-Ledger. Pro Kanal (oder pro Thema) wird eine consent_records-Zeile mit source: preference_center angehängt — Ihr GDPR-Art-7-Beweislast-Audit-Trail.
• Suppression-Liste. Auf jedem abgemeldeten Kanal wird die kanonisierte Telefonnummer/E-Mail des Kontakts mit Scope all eingefügt — eine kanalübergreifende Sperre, die jedes Send-Gate liest.
• STOP-Zaun. Ein Redis-Fast-Path-Zaun wird bei Opt-out gesetzt (und bei vollständigem Re-Opt-in gelöscht), sodass laufende Kampagnen-Batches die Änderung sehen, bevor die langsamere Datenbank-Suppression propagiert.
• Audit-Log. compliance.preference_center_updated wird aufgezeichnet, wenn Sie die Konfiguration ändern, und Kontakt-Level-Opt-in/out-Ereignisse werden im Consent-Ledger erfasst.

​

5. Semantik der GDPR-Lösch-Kachel

​

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

​

Related

• Send Gates und Pre-Send-Guards — wo die Preference-Center-Zusammenfassung neben Quiet Hours, Not-Stopp und Throttles lebt.
• Opt-Out- & Suppression-Listen — wie Scope all und CSV-Bulkimporte zu dieser Oberfläche stehen.
• Consent-Verwaltung — die Operator-seitige API, die dasselbe Consent-Ledger speichert.
• DSAR-Referenz — die getrackte Erasure-Pipeline, in die requestDataDeletion-Anträge geleitet werden.