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

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

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

이메일 구독 그룹에 대한 이 엔드포인트의 예제를 보거나 테스트하려면 다음을 참조하세요:

SMS 및 RCS 구독 그룹에 대한 이 엔드포인트의 예제를 보거나 테스트하려면 다음을 참조하세요:

필수 조건

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

참고

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

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건의 요청 사용량 제한이 적용됩니다.

요청 본문

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

이 속성은 사용자의 프로필 정보를 업데이트하는 데 사용해서는 안 됩니다. 대신 /users/track 속성을 사용하세요.

팁

기존 사용자를 구독 그룹에 추가하기: 이 엔드포인트는 기존 사용자의 구독 그룹 멤버십을 백필하거나 일괄 업데이트하는 데 권장되는 방법입니다. 요청당 최대 50개의 external_id, 이메일 주소 또는 전화번호를 전달할 수 있습니다. 사용자는 이메일 환경설정 센터 링크를 통해 직접 구독 상태를 업데이트할 수도 있습니다.

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

요청 매개변수

요청 예시

이메일

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

성공 응답 예시

201 상태 코드는 다음과 같은 응답 본문을 반환할 수 있습니다.

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

중요

엔드포인트는 email 또는 phone 값만 허용하며 둘 다 허용하지 않습니다. 두 가지를 모두 제공하면 다음과 같은 응답을 받게 됩니다: {"message":"Either an email address or a phone number should be provided, but not both."}

구독 업데이트가 전화번호에 적용되도록 하려면 E.164 형식의 전화번호(예: +15555550123)를 전송했는지, 올바른 subscription_group_id를 사용했는지, 동일한 요청 본문에서 phone만(phone과 email 둘 다가 아닌) 전달했는지 확인하세요. 여러 번호를 업데이트하려면 SMS 및 RCS에 표시된 phone 배열 형식을 사용하세요.