Mettre à jour le statut du groupe d’abonnement de l’utilisateur

Utilisez cet endpoint pour mettre à jour en masse le statut d’abonnement de jusqu’à 50 utilisateurs sur le tableau de bord de Braze.

Vous pouvez accéder au subscription_group_id d’un groupe d’abonnement en vous rendant sur la page Groupe d’abonnement.

Si vous souhaitez voir des exemples ou tester cet endpoint pour les groupes d’abonnement e-mail :

Si vous souhaitez voir des exemples ou tester cet endpoint pour les groupes d’abonnement SMS et RCS :

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation subscription.status.set.

Remarque

Si vous souhaitez utiliser cet endpoint avec les groupes d’abonnement LINE, contactez votre gestionnaire de la satisfaction client.

Comment Braze gère les états d’abonnement orphelins

Un état d’abonnement orphelin est un état d’abonnement stocké pour un numéro de téléphone ou une adresse e-mail qui n’est associé à aucun profil utilisateur. Pour les SMS, l’e-mail, WhatsApp et LINE, Braze gère les états d’abonnement orphelins de la manière suivante :

• Si un utilisateur est supprimé et qu’il est le seul utilisateur associé à un numéro de téléphone ou une adresse e-mail donné, l’état d’abonnement de ce numéro de téléphone ou de cette adresse e-mail est immédiatement supprimé.
• Si vous appelez /subscription/status/set ou /v2/subscription/status/set avec un numéro de téléphone ou une adresse e-mail qui n’est actuellement associé à aucun profil utilisateur, Braze stocke cet état d’abonnement pendant 30 jours maximum, après quoi il est automatiquement supprimé.
• Si un nouveau profil utilisateur est créé avec un numéro de téléphone ou une adresse e-mail pour lequel un état d’abonnement orphelin est stocké, cet utilisateur hérite de l’état d’abonnement stocké, mais uniquement dans la période de 30 jours. Ce délai de grâce de 30 jours est intentionnel et existe pour gérer les conditions de concurrence lorsque la création d’un utilisateur et la définition de l’état d’abonnement de son identifiant de canal se produisent dans des appels API distincts. Un exemple de cette condition de concurrence est lorsqu’une requête /subscription/status/set est traitée pour un numéro de téléphone avant que la requête /users/track créant le profil utilisateur correspondant ne soit traitée.

Limite de débit

Cet endpoint présente une limite de débit de 5 000 requêtes par minute, partagée entre les endpoints /subscription/status/set et /v2/subscription/status/set, comme documenté dans Limites de débit de l’API.

Corps de la demande

• 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
 }

Cette propriété ne doit pas être utilisée pour mettre à jour les informations de profil d’un utilisateur. Utilisez plutôt la propriété /users/track.

Conseil

Ajouter des utilisateurs existants à un groupe d’abonnement : cet endpoint est la méthode recommandée pour remplir rétroactivement ou mettre à jour en masse l’appartenance à un groupe d’abonnement pour les utilisateurs existants. Vous pouvez transmettre jusqu’à 50 external_id, adresses e-mail ou numéros de téléphone par requête. Les utilisateurs peuvent également mettre à jour leur propre statut d’abonnement via un lien de centre de préférences e-mail.

Créer de nouveaux utilisateurs avec un groupe d’abonnement : lorsque vous créez de nouveaux utilisateurs à l’aide de l’endpoint /users/track, vous pouvez définir des groupes d’abonnement dans l’objet des attributs de l’utilisateur, ce qui vous permet de créer un utilisateur et de définir l’état du groupe d’abonnement en un seul appel API.

Paramètres de la demande

Exemples de requêtes

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 et 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"]
}
'

Exemple de réponse réussie

Le code de statut 201 peut renvoyer le corps de réponse suivant.

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

Important

L’endpoint n’accepte que la valeur email ou phone, pas les deux. Si vous fournissez les deux, vous recevrez cette réponse : {"message":"Either an email address or a phone number should be provided, but not both."}

Pour que votre mise à jour d’abonnement s’applique aux numéros de téléphone, vérifiez que vous avez envoyé des numéros de téléphone au format E.164 (par exemple, +15555550123), utilisé le bon subscription_group_id et transmis phone (et non phone et email en même temps) dans le même corps de requête. Pour les mises à jour de plusieurs numéros, utilisez le format de tableau phone indiqué dans SMS et RCS.