사용자의 구독 그룹 상태 업데이트(V2)

이 엔드포인트를 사용하여 Braze 대시보드에서 최대 50명의 사용자의 구독 상태를 일괄 업데이트할 수 있습니다.

Subscription Group 페이지로 이동하여 구독 그룹의 subscription_group_id에 액세스할 수 있습니다.

이메일 구독 그룹에 대한 예제를 확인하거나 이 엔드포인트를 테스트하려면:

SMS 구독 그룹에 대한 예제를 확인하거나 이 엔드포인트를 테스트하려면:

WhatsApp 그룹에 대한 예제를 확인하거나 이 엔드포인트를 테스트하려면:

필수 조건

이 엔드포인트를 사용하려면 subscription.status.set 권한이 있는 API 키가 필요합니다.

참고

이 엔드포인트를 LINE 구독 그룹과 함께 사용하려면 고객 성공 매니저에게 문의하세요.

V1과의 차이점

V2 엔드포인트는 다음과 같은 점에서 V1 엔드포인트와 다릅니다:

• 여러 구독 그룹: V2에서는 단일 API 요청으로 여러 구독 그룹을 업데이트할 수 있지만, V1은 요청당 하나의 구독 그룹만 지원합니다.
• 이메일과 SMS를 한 번의 호출로 업데이트: external_ids를 사용하면 동일한 사용자에 대해 이메일 및 SMS 구독 그룹을 단일 API 호출로 업데이트할 수 있습니다. V1에서는 이메일 및 SMS 구독 그룹에 대해 별도의 API 호출을 해야 합니다.
• 이메일 또는 전화번호 식별자 사용: external_ids 대신 emails 또는 phones를 사용하면 동일한 요청에서 이메일 및 SMS 구독 그룹을 함께 업데이트할 수 없습니다. 이메일 구독 그룹과 SMS 구독 그룹 각각에 대해 별도의 API 호출을 해야 합니다.

중요

전화번호 형식: 전화번호는 E.164 형식이어야 합니다(예: +12223334444). E.164 형식이 아닌 전화번호는 거부됩니다.

Braze가 고아 구독 상태를 처리하는 방법

고아 구독 상태란 어떤 고객 프로필에도 연결되지 않은 전화번호 또는 이메일 주소에 저장된 구독 상태를 말합니다. SMS, 이메일, WhatsApp, LINE의 경우 Braze는 고아 구독 상태를 다음과 같이 처리합니다.

• 사용자가 삭제되었고 해당 전화번호 또는 이메일 주소와 연결된 유일한 사용자인 경우, 해당 전화번호 또는 이메일 주소의 구독 상태는 즉시 삭제됩니다.
• 현재 어떤 고객 프로필에도 연결되지 않은 전화번호 또는 이메일 주소로 /subscription/status/set 또는 /v2/subscription/status/set를 호출하면, Braze는 해당 구독 상태를 최대 30일 동안 저장하며, 이후 자동으로 삭제됩니다.
• 고아 구독 상태가 저장된 전화번호 또는 이메일 주소로 새 고객 프로필이 생성되면, 해당 사용자는 저장된 구독 상태를 상속받지만 30일 기간 내에서만 유효합니다. 이 30일 유예 기간은 의도적으로 설계된 것으로, 사용자 생성과 채널 식별자의 구독 상태 설정이 별도의 API 호출로 이루어질 때 발생하는 경합 조건을 처리하기 위해 존재합니다. 이 경합 조건의 예로는, 해당 고객 프로필을 생성하는 /users/track 요청이 처리되기 전에 전화번호에 대한 /subscription/status/set 요청이 먼저 처리되는 경우가 있습니다.

사용량 제한

이 엔드포인트는 API 사용량 제한 설명서에 명시된 바와 같이 /subscription/status/set 및 /v2/subscription/status/set 엔드포인트 간에 공유되는 분당 5,000건의 요청 사용량 제한이 적용됩니다.

요청 본문

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

팁

/users/track 엔드포인트를 사용하여 새 사용자를 생성할 때 사용자 속성 오브젝트 내에서 구독 그룹을 설정하면 한 번의 API 호출로 사용자를 생성하고 구독 그룹 상태를 설정할 수 있습니다.

요청 매개변수

중요

식별자 선택:

• 이메일 및 SMS 구독 그룹을 단일 API 호출로 업데이트하려면 external_ids를 사용하세요. 같은 요청에 emails와 phones를 모두 포함할 수 없습니다.
• external_ids 대신 emails 또는 phones를 사용하는 경우, 이메일 구독 그룹과 SMS 구독 그룹 각각에 대해 별도의 API 호출을 하세요.
• emails, phones 또는 external_ids를 개별적으로 보낼 수 있습니다.

요청 예시

다음 예시에서는 external_ids를 사용하여 단일 API 호출로 이메일 및 SMS 구독 그룹을 업데이트합니다. 이는 external_ids를 사용할 때만 가능하며, emails 또는 phones를 사용할 때는 이메일 및 SMS 구독 그룹을 한 번의 호출로 업데이트할 수 없습니다.

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

이메일

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