Actualizar el estado del grupo de suscripción del usuario (V2)

Utiliza este punto de conexión para actualizar por lotes el estado de suscripción de hasta 50 usuarios en el panel de Braze.

Puedes acceder al subscription_group_id de un grupo de suscripción navegando a la página Subscription Group.

Para ver ejemplos o probar este punto de conexión para grupos de suscripción por correo electrónico:

Para ver ejemplos o probar este punto de conexión para grupos de suscripción por SMS:

Para ver ejemplos o probar este punto de conexión para grupos de WhatsApp:

Requisitos previos

Para utilizar este punto de conexión, necesitas una clave de API con el permiso subscription.status.set.

Nota

Si te interesa utilizar este punto de conexión con los grupos de suscripción de LINE, ponte en contacto con tu administrador del éxito del cliente.

Diferencias con respecto a la versión 1

El punto de conexión V2 difiere del punto de conexión V1 en los siguientes aspectos:

• Múltiples grupos de suscripción: La versión 2 te permite actualizar varios grupos de suscripción en una sola solicitud de API, mientras que la versión 1 solo admite un grupo de suscripción por solicitud.
• Actualiza tanto el correo electrónico como el SMS en una sola llamada: Al utilizar external_ids, puedes actualizar los grupos de suscripción por correo electrónico y SMS para los mismos usuarios en una sola llamada a la API. Con la versión V1, debes realizar llamadas API independientes para los grupos de suscripción por correo electrónico y SMS.
• Uso de identificadores de correo electrónico o teléfono: Si utilizas emails o phones en lugar de external_ids, no podrás actualizar los grupos de suscripción por correo electrónico y SMS en la misma solicitud. Debes realizar llamadas API separadas: una para los grupos de suscripción por correo electrónico y otra para los grupos de suscripción por SMS.

Importante

Formato del número de teléfono: Los números de teléfono deben estar en formato E.164 (por ejemplo, +12223334444). Los números de teléfono que no están en formato E.164 son rechazados.

Cómo Braze gestiona los estados de suscripción huérfanos

Un estado de suscripción huérfano es un estado de suscripción almacenado para un número de teléfono o una dirección de correo electrónico que no está asociado con ningún perfil de usuario. Para SMS, correo electrónico, WhatsApp y LINE, Braze gestiona los estados de suscripción huérfanos de la siguiente manera:

• Si se elimina un usuario y es el único usuario asociado con un número de teléfono o una dirección de correo electrónico determinados, el estado de suscripción de ese número de teléfono o dirección de correo electrónico se elimina de inmediato.
• Si llamas a /subscription/status/set o /v2/subscription/status/set con un número de teléfono o una dirección de correo electrónico que actualmente no está asociado con ningún perfil de usuario, Braze almacena ese estado de suscripción durante un máximo de 30 días, tras lo cual se elimina automáticamente.
• Si se crea un nuevo perfil de usuario con un número de teléfono o una dirección de correo electrónico que tiene un estado de suscripción huérfano almacenado, ese usuario hereda el estado de suscripción almacenado, pero solo dentro de la ventana de 30 días. Este periodo de gracia de 30 días es intencional y existe para gestionar condiciones de carrera cuando la creación de un usuario y la configuración del estado de suscripción de su identificador de canal ocurren en llamadas a la API separadas. Un ejemplo de esta condición de carrera es cuando una solicitud /subscription/status/set se procesa para un número de teléfono antes de que se procese la solicitud /users/track que crea el perfil de usuario correspondiente.

Límite de velocidad

Este punto de conexión tiene un límite de velocidad de 5000 solicitudes por minuto compartido entre los puntos finales /subscription/status/set y /v2/subscription/status/set, como se documenta en Límites de velocidad de la API.

Cuerpo de la solicitud

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)
    }
  ]
}

Consejo

Al crear nuevos usuarios utilizando el punto de conexión /users/track, puedes establecer grupos de suscripción dentro del objeto de atributos de usuario, lo que te permite crear un usuario y establecer el estado del grupo de suscripción en una sola llamada a la API.

Parámetros de la solicitud

Importante

Selección del identificador:

• Para actualizar los grupos de suscripción por correo electrónico y SMS en una sola llamada a la API, utiliza external_ids. No puedes incluir tanto emails como phones en la misma solicitud.
• Si utilizas emails o phones en lugar de external_ids, realiza llamadas API separadas: una para los grupos de suscripción por correo electrónico y otra para los grupos de suscripción por SMS.
• Puedes enviar emails, phones o external_ids individualmente.

Ejemplos de solicitudes

El siguiente ejemplo utiliza external_ids para actualizar los grupos de suscripción por correo electrónico y SMS en una sola llamada a la API. Esto solo es posible cuando se utiliza external_ids; no se pueden actualizar los grupos de suscripción por correo electrónico y SMS en una sola llamada cuando se utiliza emails o 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]"]
    }
  ]
}

Correo electrónico

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