Update des Abo-Gruppenstatus von Nutzer:innen

Verwenden Sie diesen Endpunkt, um den Abo-Status von bis zu 50 Nutzer:innen im Braze-Dashboard im Stapelverfahren zu aktualisieren.

Sie können auf die subscription_group_id einer Abo-Gruppe zugreifen, indem Sie zur Seite Abo-Gruppe navigieren.

Wenn Sie Beispiele sehen oder diesen Endpunkt für E-Mail-Abo-Gruppen testen möchten:

Wenn Sie Beispiele sehen oder diesen Endpunkt für SMS- und RCS-Abo-Gruppen testen möchten:

Voraussetzungen

Um diesen Endpunkt zu verwenden, benötigen Sie einen API-Schlüssel mit der Berechtigung subscription.status.set.

Hinweis

Wenn Sie diesen Endpunkt mit LINE-Abo-Gruppen verwenden möchten, wenden Sie sich an Ihren Customer-Success-Manager.

Wie Braze verwaiste Abo-Status behandelt

Ein verwaister Abo-Status ist ein Abo-Status, der für eine Telefonnummer oder E-Mail-Adresse gespeichert ist, die keinem Nutzerprofil zugeordnet ist. Für SMS, E-Mail, WhatsApp und LINE behandelt Braze verwaiste Abo-Status wie folgt:

• Wenn ein:e Nutzer:in gelöscht wird und die einzige Person ist, die mit einer bestimmten Telefonnummer oder E-Mail-Adresse verknüpft ist, wird der Abo-Status für diese Telefonnummer oder E-Mail-Adresse sofort gelöscht.
• Wenn Sie /subscription/status/set oder /v2/subscription/status/set mit einer Telefonnummer oder E-Mail-Adresse aufrufen, die derzeit keinem Nutzerprofil zugeordnet ist, speichert Braze diesen Abo-Status bis zu 30 Tage lang, danach wird er automatisch gelöscht.
  • Wenn use_double_opt_in_logic auf true gesetzt ist und kein Nutzerprofil mit der angegebenen Telefonnummer verknüpft ist, wird der Abo-Status nicht aktualisiert; ein:e Nutzer:in muss existieren, um den Double-Opt-in-Workflow zu durchlaufen.
• Wenn ein neues Nutzerprofil mit einer Telefonnummer oder E-Mail-Adresse erstellt wird, für die ein verwaister Abo-Status gespeichert ist, übernimmt diese:r Nutzer:in den gespeicherten Abo-Status – allerdings nur innerhalb des 30-Tage-Fensters. Diese 30-tägige Übergangsfrist ist beabsichtigt und dient dazu, Race-Conditions zu behandeln, wenn das Erstellen eines Nutzerprofils und das Setzen des Abo-Status für den Kanal-Bezeichner in separaten API-Aufrufen erfolgen. Ein Beispiel für diese Race-Condition ist, wenn eine /subscription/status/set-Anfrage für eine Telefonnummer verarbeitet wird, bevor die /users/track-Anfrage zur Erstellung des entsprechenden Nutzerprofils verarbeitet wird.

Rate-Limit

Für diesen Endpunkt gilt ein Rate-Limit von 5.000 Anfragen pro Minute, das zwischen den Endpunkten /subscription/status/set und /v2/subscription/status/set geteilt wird, wie in API-Rate-Limits dokumentiert.

Anfragetext

• sms and rcs
• email

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
6
7
8
{
   "subscription_group_id": (required, string) the id of your subscription group,
   "subscription_state": (required, string) available values are "unsubscribed" (not in subscription group) or "subscribed" (in subscription group),
   "external_id": (required*, array of strings) the external ID of the user or users, may include up to 50 IDs,
   "phone": (required*, array of strings in E.164 format) The phone number of the user (must include at least one phone number and at most 50 phone numbers),
   "use_double_opt_in_logic": (optional, boolean) defaults to `false`; when `subscription_state` is "subscribed", set to `true` to enter the user into the SMS double opt-in workflow,
   // SMS and RCS subscription group - you must include one of external_id or phone
 }

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
6
7
8
{
   "subscription_group_id": (required, string) the id of your subscription group,
   "subscription_state": (required, string) available values are "unsubscribed" (not in subscription group) or "subscribed" (in subscription group),
   "external_id": (required*, array of strings) the external ID of the user or users, may include up to 50 IDs,
   "email": (required*, array of strings) the email address of the user (must include at least one email and at most 50 emails),
   // Email subscription group - you must include one of external_id or email
   // Note that sending an email address that is linked to multiple profiles updates all relevant profiles
 }

Diese Eigenschaft sollte nicht zum Update der Profilinformationen von Nutzer:innen verwendet werden. Verwenden Sie stattdessen die Eigenschaft /users/track.

Tipp

Bestehende Nutzer:innen zu einer Abo-Gruppe hinzufügen: Dieser Endpunkt ist die empfohlene Methode, um die Mitgliedschaft in Abo-Gruppen für bestehende Nutzer:innen nachträglich zu befüllen oder in großen Mengen zu aktualisieren. Sie können bis zu 50 external_ids, E-Mail-Adressen oder Telefonnummern pro Anfrage übergeben. Nutzer:innen können ihren eigenen Abo-Status auch über einen Link zum E-Mail-Präferenzzentrum aktualisieren.

Neue Nutzer:innen mit einer Abo-Gruppe erstellen: Wenn Sie neue Nutzer:innen über den Endpunkt /users/track erstellen, können Sie Abo-Gruppen innerhalb des Nutzerattribut-Objekts festlegen. So können Sie in einem einzigen API-Aufruf eine:n Nutzer:in erstellen und den Status der Abo-Gruppe festlegen.

Anfrageparameter

Beispielanfragen

E-Mail

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_group_id": "subscription_group_identifier",
  "subscription_state": "unsubscribed",
  "external_id": "external_identifier",
  "email": ["[email protected]", "[email protected]"]
}
'

SMS und RCS

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_group_id": "subscription_group_identifier",
  "subscription_state": "unsubscribed",
  "external_id": "external_identifier",
  "phone": ["+12223334444", "+11112223333"]
}
'

Beispiel für eine erfolgreiche Antwort

Der Statuscode 201 könnte den folgenden Antworttext zurückgeben.

1
2
3
{
    "message": "success"
}

Fehlerbehebung bei zeitweiligen Update-Fehlern

Wenn Updates von Abo-Gruppen zeitweilig fehlschlagen oder nicht synchron erscheinen, warten Sie einige Minuten zwischen den Update-Anfragen oder rufen Sie /subscription/user/status auf, um den Status der Nutzer:innen zu bestätigen, bevor Sie ein weiteres Update senden.

Wichtig

Der Endpunkt akzeptiert nur den Wert email oder phone, nicht beide. Wenn Sie beides angeben, erhalten Sie diese Antwort: {"message":"Either an email address or a phone number should be provided, but not both."}

Damit Ihr Abo-Update auf Telefonnummern angewendet wird, stellen Sie sicher, dass Sie Telefonnummern im E.164-Format gesendet haben (z. B. +15555550123), die korrekte subscription_group_id verwendet haben und phone (nicht sowohl phone als auch email) im selben Anfragetext übergeben haben. Für Updates mit mehreren Nummern verwenden Sie das phone-Array-Format, das unter SMS und RCS gezeigt wird.