Atualizar o status do grupo de inscrições do usuário (V2)

Use esse endpoint para atualizar em lote o estado da inscrição de até 50 usuários no dashboard da Braze.

É possível acessar o subscription_group_id de um grupo de inscrições navegando até a página Subscription Group.

Para ver exemplos ou testar este endpoint para grupos de inscrições para e-mail:

Para ver exemplos ou testar este endpoint para grupos de inscrições por SMS:

Para ver exemplos ou testar este endpoint para grupos de WhatsApp:

Pré-requisitos

Para usar este endpoint, você precisa de uma chave de API com a permissão subscription.status.set.

Nota

Se você tiver interesse em usar este endpoint com grupos de inscrições do LINE, entre em contato com seu gerente de sucesso do cliente.

Diferenças em relação ao V1

O endpoint V2 difere do endpoint V1 das seguintes maneiras:

• Vários grupos de inscrições: O V2 permite que você atualize vários grupos de inscrições em uma única solicitação de API, enquanto o V1 suporta apenas um grupo de inscrições por solicitação.
• Atualizar tanto e-mail quanto SMS em uma chamada: Ao usar external_ids, você pode atualizar tanto os grupos de inscrições para e-mail quanto por SMS para os mesmos usuários em uma única chamada de API. Com o V1, você deve fazer chamadas de API separadas para grupos de inscrições para e-mail e SMS.
• Usando identificadores de e-mail ou telefone: Se você usar emails ou phones em vez de external_ids, não poderá atualizar tanto os grupos de inscrições para e-mail quanto por SMS na mesma solicitação. Você deve fazer chamadas de API separadas — uma para grupos de inscrições para e-mail e uma para grupos de inscrições por SMS.

Importante

Formato do número de telefone: Os números de telefone devem estar no formato E.164 (por exemplo, +12223334444). Números de telefone que não estão no formato E.164 são rejeitados.

Como a Braze lida com estados de inscrição órfãos

Um estado de inscrição órfão é um estado de inscrição armazenado para um número de telefone ou endereço de e-mail que não está associado a nenhum perfil de usuário. Para SMS, e-mail, WhatsApp e LINE, a Braze lida com estados de inscrição órfãos da seguinte forma:

• Se um usuário for excluído e for o único usuário associado a um determinado número de telefone ou endereço de e-mail, o estado de inscrição desse número de telefone ou endereço de e-mail será excluído imediatamente.
• Se você chamar /subscription/status/set ou /v2/subscription/status/set com um número de telefone ou endereço de e-mail que não está atualmente associado a nenhum perfil de usuário, a Braze armazena esse estado de inscrição por até 30 dias, após os quais ele é automaticamente excluído.
• Se um novo perfil de usuário for criado com um número de telefone ou endereço de e-mail que possui um estado de inscrição órfão armazenado, esse usuário herda o estado de inscrição armazenado, mas apenas dentro do período de 30 dias. Esse período de tolerância de 30 dias é intencional e existe para lidar com condições de corrida quando a criação de um usuário e a definição do estado de inscrição do identificador de canal acontecem em chamadas de API separadas. Um exemplo dessa condição de corrida é quando uma solicitação /subscription/status/set é processada para um número de telefone antes que a solicitação /users/track que cria o perfil de usuário correspondente seja processada.

Limite de taxa

Esse endpoint tem um limite de taxa de 5.000 solicitações por minuto compartilhado entre os endpoints /subscription/status/set e /v2/subscription/status/set, conforme documentado em Limites de taxa da API.

Corpo da solicitação

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

Dica

Ao criar novos usuários usando o endpoint /users/track, é possível definir grupos de inscrições no objeto de atributos do usuário, o que permite criar um usuário e definir o estado do grupo de inscrições em uma única chamada de API.

Parâmetros de solicitação

Importante

Seleção de identificador:

• Para atualizar tanto os grupos de inscrições para e-mail quanto os de SMS em uma única chamada de API, use external_ids. Você não pode incluir tanto emails quanto phones na mesma solicitação.
• Se você usar emails ou phones em vez de external_ids, faça chamadas de API separadas — uma para grupos de inscrições para e-mail e outra para grupos de inscrições por SMS.
• Você pode enviar emails, phones ou external_ids individualmente.

Exemplos de solicitações

O exemplo a seguir usa external_ids para atualizar tanto os grupos de inscrições para e-mail quanto os de SMS em uma única chamada de API. Isso só é possível ao usar external_ids — você não pode atualizar tanto os grupos de inscrições para e-mail quanto os de SMS em uma chamada ao usar 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 e 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"]
    }
  ]
}
'