Skip to content

API トリガー配信を使用したキャンペーンメッセージの送信

post

/campaigns/trigger/send

このエンドポイントを使用して、API トリガー配信により、指定したユーザーに即時の1回限りのメッセージを送信します。

API トリガー配信を使用すると、メッセージのコンテンツを Braze ダッシュボード内に保存しながら、メッセージの送信タイミングと送信先を API を使用して指定できます。

Segment をターゲットにしている場合、リクエストの記録は開発者コンソールに保存されます。このエンドポイントを使用してメッセージを送信するには、API トリガーキャンペーンを構築する際に作成したキャンペーン ID が必要です。

前提条件

このエンドポイントを使用するには、campaigns.trigger.send 権限を持つ API キーを生成する必要があります。

レート制限

リクエストで Connected Audience フィルターを使用する場合、このエンドポイントには1分あたり250リクエストのレート制限が適用されます。それ以外の場合、external_id を指定すると、API レート制限に記載されているように、/messages/send/campaigns/trigger/send、および /canvas/trigger/send 間で共有される1時間あたり250,000リクエストのデフォルトのレート制限が適用されます。

Braze のエンドポイントは API リクエストのバッチ処理をサポートしています。メッセージングエンドポイントへの単一のリクエストは、次のいずれかに到達できます。

  • それぞれに個別のメッセージパラメーターを持つ、最大50個の特定の external_ids
  • リクエスト内で Connected Audience オブジェクトとして定義された、任意のサイズのオーディエンスセグメント

Braze のエンドポイントは API リクエストのバッチ処理をサポートしています。メッセージングエンドポイントへの単一のリクエストは、次のいずれかに到達できます。

  • それぞれに個別のメッセージパラメーターを持つ、最大50個の特定の external_ids
  • リクエストで Connected Audience オブジェクトとして定義された、任意のサイズのオーディエンスセグメント

リクエスト本文

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

リクエストパラメーター

  • 受信者配列には最大50個のオブジェクトを含めることができ、各オブジェクトには単一のユーザー識別子(external_user_iduser_alias、または email)とオプションの trigger_properties オブジェクトが含まれます。
  • send_to_existing_onlytrue(デフォルト)の場合、Braze は既存ユーザーにのみメッセージを送信します。受信者オブジェクト内の識別子(external_user_iduser_alias、または email)が既存のユーザーと一致しない場合、API は dispatch_id を含む 201 成功応答を返しますが、送信は内部的にキャンセルされ、メッセージは配信されません。external_user_id の場合、結果は Unknown External User ID として記録され、Currents イベントは生成されません。false に設定し、属性オブジェクトが提供された場合、Braze はユーザーが存在しない場合に新規ユーザーを作成します。なお、send_to_existing_onlyfalse に設定することはユーザーエイリアスではサポートされていません—このエンドポイントを通じてエイリアスのみの新規ユーザーを作成することはできません。エイリアスのみのユーザーに送信するには、そのユーザーが既に Braze に存在している必要があります。

ユーザーのサブスクリプショングループのステータスは、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 です。このエンドポイントを使用すると、バッチ処理されたユーザーセット全体に対して単一の dispatch_id を受け取ります。dispatch_id の詳細については、ディスパッチ ID の動作に関するドキュメントを参照してください。

リクエストで致命的なエラーが発生した場合のエラーコードと説明については、エラーとレスポンスを参照してください。

キャンペーンの属性オブジェクト

Braze には attributes というメッセージングオブジェクトがあり、API トリガーキャンペーンを送信する前に、ユーザーの属性や値を追加・作成・更新できます。この API 呼び出しとして campaign/trigger/send エンドポイントを使用すると、キャンペーンを処理して送信する前にユーザー属性オブジェクトが処理されます。これにより、競合による問題が発生するリスクを最小限に抑えることができます。

New Stuff!