APIトリガー配信でキャンペーンメッセージを送る
APIMETHOD POST CORE_ENDPOINT| <div class='api_type'><div class='method post '>post</div>
/campaigns/trigger/send
</div>
このエンドポイントを使用して、API トリガー配信を介して、指定したユーザーに即時の1回限りのメッセージを送信します。
APIトリガー配信により、Brazeダッシュボード内にメッセージコンテンツを収容しながら、APIを介してメッセージの送信タイミングと送信先を指定できる。
セグメントをターゲットにしている場合、リクエストの記録は開発者コンソールに保存されます。このエンドポイントを使用してメッセージを送信するには、API トリガーキャンペーンを構築する際にキャンペーン ID を作成しておく必要があります。
前提条件
このエンドポイントを使用するには、campaigns.trigger.send
権限を持つ API キーを生成する必要があります。
レート制限
要求本文:
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 will 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' will only send to users in the audience
"recipients": (optional, array; if not provided and broadcast is not set to `false`, message will send 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 will apply to this user (these key-value pairs will 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 will 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 will be 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 will be 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 |
オプション | ブール値 | キャンペーンまたはキャンバスが対象とするSegment全体にメッセージを送信する場合は、broadcast をtrue に設定する必要があります。このパラメーターはデフォルトで false です (2017 年 8 月 31 日現在)。broadcast が true に設定されている場合、recipients リストを含めることはできません。ただし、設定 broadcast: true の場合は注意が必要です。意図せずにこのフラグを設定すると、想定よりも大きなオーディエンスにメッセージが送信される可能性があるためです。 |
audience |
オプション | 接続されたオーディエンスオブジェクト | 接続オーディエンスを参照してください。 |
recipients |
オプション | 配列 | 受信者オブジェクトを参照してください。send_to_existing_only が false の場合、属性オブジェクトが含まれていなければなりません。recipients が提供されず、broadcast がtrueに設定されている場合、メッセージはキャンペーンがターゲットとしているセグメント全体に送信される。 |
attachments |
オプション | 配列 | broadcast が true に設定されている場合、attachments リストを含めることはできません。 |
- 受信者配列には最大50個のオブジェクトを含めることができ、各オブジェクトには1つの
external_user_id
文字列とtrigger_properties
オブジェクトが含まれます。 send_to_existing_only
がtrue
の場合、Braze は既存ユーザーにのみメッセージを送信します。ただし、このフラグは、ユーザーのエイリアスでは使えません。send_to_existing_only
がfalse
の場合、属性が含まれていなければなりません。Brazeは、メッセージを送信する前に、id
と属性を持つユーザーを作成する。
メールアドレスによる受信者の指定は、現在早期アクセス中である。この早期アクセスへ参加することに興味がある場合は、カスタマーサクセスマネージャーにお問い合わせください。
ユーザーのサブスクリプショングループのステータスは、attributes
オブジェクト内にsubscription_groups
パラメータを含めることで更新できる。詳細については、ユーザー属性オブジェクトを参照してください。
例のリクエスト
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 です。このエンドポイントを使用すると、バッチ処理されたユーザーセット全体に対して1つの dispatch_id
を受け取ります。dispatch_id
の詳細については、ディスパッチ ID の動作に関するドキュメントを参照してください。
リクエストが致命的なエラーに遭遇した場合、エラーコードと説明についてはエラーとレスポンスを参照のこと。
キャンペーン用アトリビューションオブジェクト
Brazeには、attributes
というメッセージングオブジェクトがあり、APIトリガーのキャンペーンを送る前に、ユーザーの属性や値を追加、作成、更新することができる。この API 呼び出しとして campaign/trigger/send
エンドポイントを使用すると、キャンペーンを処理して送信する前に、ユーザー属性オブジェクトが処理されます。これにより、競合 による問題が発生するリスクを最小限に抑えることができます。
このエンドポイントのキャンバスバージョンをお探し?API トリガー配信によるキャンバスメッセージの送信を確認してください。