Skip to content

API 트리거 전송을 사용하여 캠페인 메시지 보내기

post

/campaigns/trigger/send

core endpoint

이 엔드포인트를 사용하면 API 트리거 전송을 통해 지정된 사용자에게 즉각적인 일회성 메시지를 보낼 수 있습니다.

API 트리거 전송을 사용하면 메시지 콘텐츠를 Braze 대시보드 내에 보관하면서 API를 사용하여 메시지 전송 시기와 수신자를 지정할 수 있습니다.

Segment를 타겟팅하는 경우, 요청 기록이 개발자 콘솔에 저장됩니다. 이 엔드포인트로 메시지를 보내려면 API 트리거 Campaign을 구축할 때 생성한 Campaign ID가 있어야 합니다.

See me in Postman

필수 조건

이 엔드포인트를 사용하려면 campaigns.trigger.send 권한이 있는 API 키를 생성해야 합니다.

사용량 제한

요청에서 Connected 오디언스 필터를 사용하는 경우, 이 엔드포인트에 분당 250건의 요청 제한이 적용됩니다. 그렇지 않은 경우 external_id를 지정하면, 이 엔드포인트는 API 사용량 제한 설명서에 명시된 엔드포인트 간에 공유되는 시간당 250,000건의 요청이라는 기본 사용량 제한이 적용됩니다.

Braze 엔드포인트는 API 요청의 일괄 처리를 지원합니다. 메시징 엔드포인트에 대한 단일 요청은 다음 중 하나에 해당할 수 있습니다:

  • 최대 50개의 특정 external_ids(각각 개별 메시지 매개변수 포함)
  • 요청에서 Connected 오디언스 오브젝트로 정의된 모든 규모의 오디언스 Segment

Braze 엔드포인트는 API 요청의 일괄 처리를 지원합니다. 메시징 엔드포인트에 대한 단일 요청은 다음 중 하나에 해당할 수 있습니다:

  • 최대 50개의 특정 external_ids(각각 개별 메시지 매개변수 포함)
  • 요청에서 Connected 오디언스 오브젝트로 정의된 모든 규모의 오디언스 Segment

요청 본문

1
2

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  "campaign_id": (required, string) see campaign identifier,
  "send_id": (optional, string) see send identifier,
  "trigger_properties": (optional, object) personalization key-value pairs that apply to all users in this request,
  "broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" is omitted,
  "audience": (optional, connected audience object) see connected audience,
  // Including 'audience' sends to only users in the audience
  "recipients": (optional, array; if not provided and broadcast is not set to `false`, message sends to the entire segment targeted by the campaign)
    [
      {
      // Either "external_user_id" or "user_alias" or "email" is required. Requests must specify only one.
      "user_alias": (optional, user alias object) user alias of user to receive message,
      "external_user_id": (optional, string) external identifier of user to receive message,
      "email": (optional, string) email address of user to receive message,
      "prioritization": (optional, array) prioritization array; required when using email,
      "trigger_properties": (optional, object) personalization key-value pairs that apply to this user (these key-value pairs override any keys that conflict with the parent trigger_properties),
      "send_to_existing_only": (optional, boolean) defaults to true, can't be used with user aliases; if set to `false`, an attributes object must also be included,
      "attributes": (optional, object) fields in the attributes object create or update an attribute of that name with the given value on the specified user profile before the message is sent and existing values are overwritten
    }
  ],
  "attachments": (optional, array) array of JSON objects that define the files you need attached, defined by "file_name" and "url",
    [
      {
       "file_name": (required, string) the name of the file you want to attach to your email, excluding the extension (for example, ".pdf"). Attach files up to 2 MB. This is required if you use "attachments",
       "url": (required, string) the corresponding URL of the file you want to attach to your email. The file name's extension is detected automatically from the URL defined, which should return the appropriate "Content-Type" as a response header. This is required if you use "attachments",
      }
    ]
}

요청 매개변수

수신자 확인 동작

이 섹션에서는 Braze가 전송할 고객 프로필을 선택하는 방법과 프로필이 선택되지 않을 때 어떤 일이 발생하는지 설명합니다.

사용자의 구독 그룹 상태는 attributes 오브젝트 내에 subscription_groups 매개변수를 포함하여 업데이트할 수 있습니다. 자세한 내용은 사용자 속성 오브젝트를 참조하세요.

수신자 제한 및 프로필 생성

이 엔드포인트의 수신자 제한 및 프로필 생성 작동 방식에 대해 자세히 알아보세요.

  • recipients 배열에는 최대 50개의 오브젝트가 포함될 수 있으며, 각 오브젝트에는 단일 external_user_id 문자열과 trigger_properties 오브젝트가 포함됩니다.
  • send_to_existing_only가 true(기본값)일 때, Braze는 기존 사용자에게만 메시지를 전송합니다.
  • send_to_existing_only가 false이고 attributes 오브젝트가 제공되면, Braze는 사용자가 존재하지 않을 경우 새 사용자를 생성합니다.
  • 신규 프로필에는 send_to_existing_only: false와 함께 attributes가 필요합니다. Braze는 동일한 수신자 내의 attributes 오브젝트에서 전송 전 생성 또는 업데이트를 실행합니다. send_to_existing_only를 false로 설정하되 attributes를 생략하거나 빈 오브젝트를 전송하면, Braze는 동일한 방식으로 프로필 데이터를 채우지 않으므로 이 패턴이 의도하는 “사용자 생성 또는 업데이트 후 전송” 동작을 얻을 수 없습니다.
  • 이메일 및 SMS 주소 지정. 아직 Braze에 없는 사용자에게 대부분의 이메일 또는 SMS API 트리거 전송을 하려면, attributes 내에 필요한 전달 필드(예: email 또는 워크스페이스에서 SMS에 사용하는 전화 속성)를 포함하세요. 동일한 호출에서 옵트인 상태를 변경해야 하는 경우 구독 그룹 멤버십 또는 구독 상태도 설정할 수 있습니다.
  • Campaign 적격성. 프로필이 존재하거나 업데이트된 후에도 해당 사용자는 Campaign의 대시보드 타겟 오디언스 및 채널 전송 규칙(예: 이메일 옵트인)과 일치해야 합니다. 그렇지 않으면 Braze는 메시지를 전송하지 않습니다.
  • send_to_existing_only를 false로 설정하는 것은 사용자 별칭에 대해 지원되지 않습니다. 새 별칭 전용 사용자는 이 엔드포인트를 통해 생성할 수 없습니다. 별칭 전용 사용자에게 전송하려면, 해당 사용자가 이미 Braze에 존재해야 합니다.

이메일 식별자 및 우선순위 동점

이메일로 수신자를 식별할 때, Braze는 prioritization을 사용합니다. Braze는 prioritization이 하나의 프로필을 반환할 때만 전송합니다.

  • email을 식별자로 사용하는 경우, Braze는 prioritization을 사용하여 수신자를 확인합니다.
  • prioritization이 동점을 반환하면, Braze는 전송하지 않습니다.
  • 동점이 해소되고 prioritization이 하나의 프로필을 반환하면 Braze가 전송합니다. 예를 들어, 프로필 업데이트로 인해 한 사용자의 정렬 필드가 변경되면, prioritization이 프로필을 고유하게 식별할 수 있게 된 후 Braze가 전송합니다(재시도 동작 및 send_to_existing_only 참조).
  • prioritization이 프로필을 반환하지 않는 경우에도 Braze는 전송하지 않습니다.

재시도 동작 및 send_to_existing_only

prioritization이 정확히 하나의 프로필을 반환하지 않을 때 어떤 일이 발생하는지 알아보세요.

  • prioritization이 정확히 하나의 고객 프로필을 반환하지 않으면, Braze는 최대 40회까지 확인을 재시도합니다. 이 재시도 동작은 예상된 것입니다.
  • send_to_existing_only 설정은 prioritization 동점 동작을 변경하지 않습니다. 이 설정이 true이든 false이든 동일한 동점 및 재시도 동작이 적용됩니다.

요청 예시

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

curl --location --request POST 'https://rest.iad-01.braze.com/campaigns/trigger/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "campaign_id": "campaign_identifier",
  "send_id": "send_identifier",
  "trigger_properties": "",
  "broadcast": false,
  "audience": {
    "AND": [
      {
        "custom_attribute": {
          "custom_attribute_name": "eye_color",
          "comparison": "equals",
          "value": "blue"
        }
      },
      {
        "custom_attribute": {
          "custom_attribute_name": "favorite_foods",
          "comparison": "includes_value",
          "value": "pizza"
        }
      },
      {
        "OR": [
          {
            "custom_attribute": {
              "custom_attribute_name": "last_purchase_time",
              "comparison": "less_than_x_days_ago",
              "value": 2
            }
          },
          {
            "push_subscription_status": {
              "comparison": "is",
              "value": "opted_in"
            }
          }
        ]
      },
      {
        "email_subscription_status": {
          "comparison": "is_not",
          "value": "subscribed"
        }
      },
      {
        "last_used_app": {
          "comparison": "after",
          "value": "2019-07-22T13:17:55+0000"
        }
      }
    ]
  },
  "recipients": [
    {
      "user_alias": {
        "alias_name" : "example_name",
        "alias_label" : "example_label"
      },
      "external_user_id": "external_user_identifier",
      "trigger_properties": "",
      "send_to_existing_only": true,
      "attributes": {
        "first_name" : "Alex"
      }
    }
  ],
  "attachments": [
    {
      "file_name" : "YourFileName",
      "url" : "https://exampleurl.com/YourFileName.pdf"
    }
  ]
}'

응답 세부 정보

메시지 전송 엔드포인트 응답에는 메시지 발송을 참조할 수 있도록 메시지의 dispatch_id가 포함됩니다. dispatch_id는 메시지 발송의 ID로, Braze에서 전송하는 각 전송에 대한 고유 ID입니다. 이 엔드포인트를 사용하면 전체 배치 사용자 집합에 대해 단일 dispatch_id를 받게 됩니다. dispatch_id에 대한 자세한 내용은 디스패치 ID 동작 설명서를 참조하세요.

요청에 심각한 오류가 발생하면 오류 코드와 설명은 오류 및 응답을 참조하세요.

Campaign용 속성 오브젝트

Braze에는 attributes라는 메시징 오브젝트가 있어, API 트리거 Campaign을 전송하기 전에 사용자의 속성과 값을 추가, 생성 또는 업데이트할 수 있습니다. campaign/trigger/send 엔드포인트를 사용하면 이 API 호출이 사용자 속성 오브젝트를 먼저 처리한 후 Campaign을 처리하고 전송합니다. 이를 통해 경합 조건으로 인해 발생할 수 있는 문제의 위험을 최소화할 수 있습니다.
New Stuff!