API 트리거 전송을 사용하여 캠페인 메시지 보내기
이 엔드포인트를 사용하면 API 트리거 전송을 통해 지정된 사용자에게 즉각적인 일회성 메시지를 보낼 수 있습니다.
API 트리거 전송을 사용하면 메시지 콘텐츠를 Braze 대시보드 내에 보관하면서 API를 사용하여 메시지 전송 시기와 수신자를 지정할 수 있습니다.
세그먼트를 타겟팅하는 경우, 요청 기록이 개발자 콘솔에 저장됩니다. 이 엔드포인트로 메시지를 보내려면 API 트리거 캠페인을 구축할 때 생성한 캠페인 ID가 있어야 합니다.
필수 조건
이 엔드포인트를 사용하려면 campaigns.trigger.send 권한이 있는 API 키를 생성해야 합니다.
사용량 제한
요청 시 Connected 오디언스 필터를 사용할 경우, 이 엔드포인트에 분당 250건의 요청 제한이 적용됩니다. 그렇지 않은 경우 external_id를 지정하면, 이 엔드포인트는 API 사용량 제한 설명서에 명시된 대로 /messages/send, /campaigns/trigger/send 및 /canvas/trigger/send 간에 공유되는 시간당 250,000건의 요청이라는 기본 사용량 제한이 적용됩니다.
Braze 엔드포인트는 API 요청의 일괄 처리를 지원합니다. 메시징 엔드포인트에 대한 단일 요청은 다음 중 하나에 해당할 수 있습니다:
- 최대 50개의 특정
external_ids(각각 개별 메시지 매개변수 포함) - 요청에서 Connected 오디언스 오브젝트로 정의된 모든 규모의 오디언스 세그먼트
Braze 엔드포인트는 API 요청의 일괄 처리를 지원합니다. 메시징 엔드포인트에 대한 단일 요청은 다음 중 하나에 해당할 수 있습니다:
- 최대 50개의 특정
external_ids(각각 개별 메시지 매개변수 포함) - 요청에서 연결된 오디언스 오브젝트로 정의된 모든 규모의 오디언스 세그먼트
요청 본문
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",
}
]
}
요청 매개변수
| 매개변수 | 필수 | 데이터 유형 | 설명 |
|---|---|---|---|
campaign_id |
필수 | 문자열 | 캠페인 식별자를 참조하세요. |
send_id |
선택 사항 | 문자열 | 전송 식별자를 참조하세요. |
trigger_properties |
선택 사항 | 오브젝트 | 트리거 등록정보를 참조하세요. 개인화 키-값 페어는 이 요청의 모든 사용자에게 적용됩니다. |
broadcast |
선택 사항 | 부울 | Braze 대시보드에서 캠페인의 타겟 오디언스로 구성된 전체 세그먼트에 메시지를 전송할 때 broadcast를 true로 설정해야 합니다. 이 매개변수는 기본적으로 false로 설정됩니다(2017년 8월 31일 기준). broadcast가 true로 설정되면 recipients 목록을 포함할 수 없습니다. 그러나 이 플래그를 실수로 설정하면 예상보다 많은 오디언스에게 메시지를 보낼 수 있으므로 broadcast: true를 설정할 때는 주의하세요. |
audience |
선택 사항 | 연결된 오디언스 오브젝트 | 연결된 오디언스를 참조하세요. audience를 포함하면, 커스텀 속성 및 구독 상태와 같은 정의된 필터와 일치하는 사용자에게만 메시지가 전송됩니다. |
recipients |
선택 사항 | 배열 | 수신자 오브젝트를 참조하세요.send_to_existing_only가 false인 경우 속성 오브젝트를 포함해야 합니다.recipients가 제공되지 않고 broadcast가 true로 설정된 경우, Braze 대시보드에서 캠페인의 타겟 오디언스로 구성된 전체 세그먼트에 메시지가 전송됩니다. email이 식별자인 경우 수신자 오브젝트에 prioritization을 포함해야 합니다. |
attachments |
선택 사항 | 배열 | broadcast가 true로 설정되어 있으면 attachments 목록을 포함할 수 없습니다. |
- 수신자 배열에는 최대 50개의 오브젝트가 포함될 수 있으며, 각 오브젝트에는 단일 사용자 식별자(
external_user_id,user_alias또는email)와 선택적trigger_properties오브젝트가 포함됩니다. send_to_existing_only가true(기본값)일 때, Braze는 기존 사용자에게만 메시지를 전송합니다. 수신자 오브젝트의 식별자(external_user_id,user_alias또는email)가 기존 사용자와 일치하지 않으면, API는 여전히dispatch_id와 함께201성공 응답을 반환하지만, 전송은 내부적으로 취소되며 메시지는 전달되지 않습니다.external_user_id의 경우 결과는Unknown External User ID로 기록되며 커런츠 이벤트는 생성되지 않습니다.false로 설정되고 속성 오브젝트가 제공되면, Braze는 사용자가 존재하지 않을 경우 새 사용자를 생성합니다.send_to_existing_only를false로 설정하는 것은 사용자 별칭에 대해 지원되지 않으며—새 별칭 전용 사용자는 이 엔드포인트를 통해 생성할 수 없습니다. 별칭 전용 사용자에게 전송하려면, 해당 사용자가 이미 Braze에 존재해야 합니다.
dispatch_id와 함께 201 응답은 Braze가 요청을 수락했음을 확인하지만, 메시지 전달을 보장하지는 않습니다. 사용자를 찾을 수 없거나, 구독을 취소했거나, 해당 채널에 대한 유효한 연락처 주소가 없는 경우 전달이 실패할 수 있습니다.
사용자의 구독 그룹 상태는 attributes 오브젝트 내에 subscription_groups 매개변수를 포함하여 업데이트할 수 있습니다. 자세한 내용은 사용자 속성 오브젝트를 참조하세요.
이 엔드포인트에서는 segment_id 매개변수가 지원되지 않습니다. 세그먼트를 타겟팅하려면, Braze 대시보드에서 캠페인의 타겟 오디언스 설정에서 세그먼트를 구성하고 "broadcast": true를 사용하거나, 연결된 오디언스 필터와 함께 audience 매개변수를 사용하세요.
요청 예시
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 동작 설명서를 참조하세요.
요청에 심각한 오류가 발생하면 오류 코드와 설명은 오류 및 응답을 참조하세요.
캠페인용 속성 오브젝트
Braze에는 attributes라는 메시징 오브젝트가 있어, API 트리거 캠페인을 전송하기 전에 사용자의 속성과 값을 추가, 생성 또는 업데이트할 수 있습니다. campaign/trigger/send 엔드포인트를 사용하면 이 API 호출이 사용자 속성 오브젝트를 먼저 처리한 후 캠페인을 처리하고 전송합니다. 이를 통해 경합 조건으로 인해 발생할 수 있는 문제의 위험을 최소화할 수 있습니다.
이 엔드포인트의 캔버스 버전을 찾고 계신가요? API 트리거 전송을 사용하여 캔버스 메시지 보내기를 확인하세요.
GitHub 에서 이 페이지를 편집합니다.