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

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 Subscription Group.

Pour consulter des exemples ou tester cet endpoint pour les groupes d’abonnement par e-mail :

Pour consulter des exemples ou tester cet endpoint pour les groupes d’abonnement SMS :

Pour consulter des exemples ou tester cet endpoint pour les groupes WhatsApp :

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.

Différences par rapport à la V1

L’endpoint V2 diffère de l’endpoint V1 de la manière suivante :

• Groupes d’abonnement multiples : La V2 vous permet de mettre à jour plusieurs groupes d’abonnement en une seule requête API, tandis que la V1 ne prend en charge qu’un seul groupe d’abonnement par requête.
• Mise à jour simultanée des abonnements e-mail et SMS : Lorsque vous utilisez external_ids, vous pouvez mettre à jour les groupes d’abonnement par e-mail et par SMS pour les mêmes utilisateurs en un seul appel API. Avec la V1, vous devez effectuer des appels API distincts pour les groupes d’abonnement par e-mail et par SMS.
• Utilisation des identifiants e-mail ou téléphone : Si vous utilisez emails ou phones au lieu de external_ids, vous ne pouvez pas mettre à jour à la fois les groupes d’abonnement par e-mail et par SMS dans la même requête. Vous devez effectuer des appels API distincts : un pour les groupes d’abonnement par e-mail et un autre pour les groupes d’abonnement par SMS.

Important

Format du numéro de téléphone : Les numéros de téléphone doivent être au format E.164 (par exemple, +12223334444). Les numéros de téléphone qui ne sont pas au format E.164 sont rejetés.

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 requête

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

1
2
3
4
5
6
7
8
9
10
11
12
{
  "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)
    }
  ]
}

Conseil

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 requête

Important

Sélection de l’identifiant :

• Pour mettre à jour les groupes d’abonnement par e-mail et par SMS en un seul appel API, utilisez external_ids. Vous ne pouvez pas inclure à la fois emails et phones dans la même requête.
• Si vous utilisez emails ou phones au lieu de external_ids, effectuez des appels API distincts : un pour les groupes d’abonnement par e-mail et un pour les groupes d’abonnement par SMS.
• Vous pouvez envoyer emails, phones ou external_ids individuellement.

Exemples de requêtes

L’exemple suivant utilise external_ids pour mettre à jour les groupes d’abonnement par e-mail et par SMS en un seul appel API. Cela n’est possible que lorsque vous utilisez external_ids — vous ne pouvez pas mettre à jour à la fois les groupes d’abonnement par e-mail et par SMS en un seul appel lorsque vous utilisez emails ou phones.

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 et WhatsApp

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",
      "phones":["+12223334444","+15556667777"]
    }
  ]
}
'