Actualizar el estado del grupo de suscripción del usuario

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.

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

Si quieres ver ejemplos o probar este punto de conexión para grupos de suscripción SMS y RCS:

Requisitos previos

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

Nota

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

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

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

Esta propiedad no debe utilizarse para actualizar la información del perfil de un usuario. Utiliza en su lugar la propiedad /users/track.

Consejo

Añadir usuarios existentes a un grupo de suscripción: Este punto de conexión es la forma recomendada de rellenar o actualizar de forma masiva la pertenencia a grupos de suscripción para usuarios existentes. Puedes pasar hasta 50 external_ids, direcciones de correo electrónico o números de teléfono por solicitud. Los usuarios también pueden actualizar su propio estado de suscripción a través de un enlace de centro de preferencias de correo electrónico.

Crear nuevos usuarios con un grupo de suscripción: 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

Ejemplos de solicitudes

Correo electrónico

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

Ejemplo de respuesta correcta

El código de estado 201 podría devolver el siguiente cuerpo de respuesta.

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

Importante

El punto de conexión solo acepta el valor email o phone, no ambos. Si proporcionas ambos, recibirás esta respuesta: {"message":"Either an email address or a phone number should be provided, but not both."}