Diese Seite wurde automatisch übersetzt und kann Ungenauigkeiten enthalten. Um einen Übersetzungsfehler zu melden, nutzen Sie das Feedback unten im Inhaltsverzeichnis rechts auf der Seite.

Abo-Gruppenstatus von Nutzer:innen aktualisieren (V2)

post

/v2/subscription/status/set

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.

Um Beispiele zu sehen oder diesen Endpunkt für E-Mail-Abo-Gruppen zu testen:

See me in Postman

Um Beispiele zu sehen oder diesen Endpunkt für SMS-Abo-Gruppen zu testen:

See me in Postman

Um Beispiele zu sehen oder diesen Endpunkt für WhatsApp-Gruppen zu testen:

See me in Postman

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 bitte an Ihren Customer-Success-Manager.

Für LINE-Abo-Gruppen empfehlen wir, ein angepasstes Attribut zu verwenden, um die Einwilligung über die Website oder App separat zu verfolgen, und dann Campaigns mithilfe dieses angepassten Attributs in Kombination mit dem LINE-Abo-Status zu targeten. Dieser Ansatz stellt sicher, dass Ihr Abo-Status korrekt die Nutzer:innen widerspiegelt, die sich tatsächlich in der LINE-App angemeldet haben. Das manuelle Hinzufügen von Nutzer:innen zu LINE-Abo-Gruppen über die API kann zu nicht synchronisierten Zuständen und fehlgeschlagenen Sendungen führen, da Braze Nutzer:innen nicht erneut in der LINE-App abonnieren oder Nachrichten an Nutzer:innen senden kann, die ein Konto in LINE blockiert haben.

Unterschiede zu V1

Der V2-Endpunkt unterscheidet sich vom V1-Endpunkt in folgenden Punkten:

Mehrere Abo-Gruppen: Mit V2 können Sie mehrere Abo-Gruppen in einer einzigen API-Anfrage aktualisieren, während V1 nur eine Abo-Gruppe pro Anfrage unterstützt.
E-Mail und SMS in einem Aufruf aktualisieren: Bei Verwendung von external_ids können Sie sowohl E-Mail- als auch SMS-Abo-Gruppen für dieselben Nutzer:innen in einem einzigen API-Aufruf aktualisieren. Bei V1 müssen Sie separate API-Aufrufe für E-Mail- und SMS-Abo-Gruppen durchführen.
Verwendung von E-Mail- oder Telefon-Bezeichnern: Wenn Sie emails oder phones anstelle von external_ids verwenden, können Sie nicht sowohl E-Mail- als auch SMS-Abo-Gruppen in derselben Anfrage aktualisieren. Sie müssen separate API-Aufrufe durchführen – einen für E-Mail-Abo-Gruppen und einen für SMS-Abo-Gruppen.

Wichtig

Telefonnummernformat: Telefonnummern müssen im E.164-Format angegeben werden (zum Beispiel +12223334444). Telefonnummern, die nicht im E.164-Format vorliegen, werden abgelehnt.

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

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

{
  "subscription_groups":[
    {
      "subscription_group_id": (required, string),
      "subscription_state": (required, string),
      "external_ids": (required*, array of strings),
      "emails": (required*, array of strings),
      "phones": (required*, array of strings in E.164 format),
      "use_double_opt_in_logic": (optional, boolean)
    }
  ]
}

Tipp

Bei der Erstellung neuer Nutzer:innen über den /users/track-Endpunkt 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 Abo-Gruppenstatus festlegen.

Anfrageparameter

Parameter	Erforderlich	Datentyp	Beschreibung
`subscription_group_id`	Erforderlich	String	Die `id` Ihrer Abo-Gruppe.
`subscription_state`	Erforderlich	String	Verfügbare Werte sind `unsubscribed` (nicht in Abo-Gruppe) oder `subscribed` (in Abo-Gruppe).
`external_ids`	Erforderlich*	String-Array	Die `external_id` der Nutzer:innen, kann bis zu 50 `id`s umfassen.
`emails`	Erforderlich*	String oder String-Array	Die E-Mail-Adresse der Nutzer:innen, kann als String-Array übergeben werden. Es muss mindestens eine E-Mail-Adresse angegeben werden (maximal 50). Wenn mehrere Nutzer:innen (`external_id`) im selben Workspace dieselbe E-Mail-Adresse haben, werden alle Nutzer:innen, die diese E-Mail-Adresse teilen, mit den Änderungen der Abo-Gruppe aktualisiert.
`phones`	Erforderlich*	String im E.164-Format	Sie können die Telefonnummern der Nutzer:innen als String-Array übergeben. Es muss mindestens eine Telefonnummer enthalten sein (bis zu 50). Telefonnummern müssen im E.164-Format angegeben werden (zum Beispiel `+12223334444`). Wenn mehrere Nutzer:innen (`external_id`) im selben Workspace dieselbe Telefonnummer haben, werden alle Nutzer:innen, die diese Telefonnummer teilen, mit denselben Änderungen der Abo-Gruppe aktualisiert.
`use_double_opt_in_logic`	Optional	Boolescher Wert	Standardmäßig `false`, wenn nicht angegeben. Setzen Sie diesen Parameter für SMS-Abo-Gruppen auf `true`, um die Nutzer:innen in den SMS-Double-Opt-in-Workflow aufzunehmen, wenn ihr Abo-Status auf `subscribed` gesetzt wird. Nutzer:innen, die auf diese Weise in den Double-Opt-in-Workflow aufgenommen werden, erhalten höchstens eine Opt-in-Anfrage-Antwortnachricht pro Tag, unabhängig davon, wie oft sie in den Workflow aufgenommen werden. Wenn dieser Parameter weggelassen oder auf `false` gesetzt wird, werden Nutzer:innen abonniert, ohne den Double-Opt-in-Workflow zu durchlaufen. Dieser Parameter gilt nicht für E-Mail-Abo-Gruppen.

Wichtig

Auswahl des Bezeichners:

Um sowohl E-Mail- als auch SMS-Abo-Gruppen in einem einzigen API-Aufruf zu aktualisieren, verwenden Sie external_ids. Es ist nicht möglich, sowohl emails als auch phones in derselben Anfrage anzugeben.
Wenn Sie emails oder phones anstelle von external_ids verwenden, führen Sie separate API-Aufrufe durch – einen für E-Mail-Abo-Gruppen und einen für SMS-Abo-Gruppen.
Sie können emails, phones oder external_ids einzeln senden.

Beispielanfragen

Das folgende Beispiel verwendet external_ids, um sowohl E-Mail- als auch SMS-Abo-Gruppen in einem einzigen API-Aufruf zu aktualisieren. Dies ist nur bei Verwendung von external_ids möglich – bei Verwendung von emails oder phones können Sie nicht sowohl E-Mail- als auch SMS-Abo-Gruppen in einem Aufruf aktualisieren.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_groups":[
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "external_ids":["example-user","[email protected]"]
    },
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "external_ids":["example-user","[email protected]"]
    }
  ]
}

E-Mail

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

SMS und WhatsApp

curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_groups":[
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "phones":["+12223334444","+15556667777"]
    }
  ]
}
'

New Stuff!