APIトリガー配信を使用したCampaignメッセージの送信

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

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

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

前提条件

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

レート制限

リクエストでConnected Audienceフィルターを使用する場合、このエンドポイントには1分あたり250リクエストのレート制限が適用されます。それ以外の場合、external_id を指定すると、APIレート制限に記載されているエンドポイント間で共有される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",
      }
    ]
}

リクエストパラメーター

受信者の解決動作

このセクションでは、Brazeが送信先のユーザープロファイルをどのように選択するか、および1つのプロファイルが選択されなかった場合に何が起こるかについて説明します。

ユーザーのサブスクリプショングループのステータスは、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 が1つのプロファイルを返した場合にのみ送信します。

• email を識別子として使用する場合、Brazeは prioritization を使用して受信者を解決します。
• prioritization が同点を返した場合、Brazeは送信しません。
• 同点が解消され、prioritization が1つのプロファイルを返した後にBrazeは送信します。たとえば、プロファイルの更新によってあるユーザーの順序フィールドが変更された場合、prioritization がプロファイルを一意に識別できるようになった時点でBrazeは送信します（リトライ動作と send_to_existing_onlyを参照）。
• prioritization がプロファイルを返さない場合も、Brazeは送信しません。

リトライ動作とsend_to_existing_only

prioritization が正確に1つのプロファイルを返さない場合に何が起こるかについて説明します。

• prioritization が正確に1つのユーザープロファイルを返さない場合、Brazeは最大40回まで解決をリトライします。このリトライ動作は想定されたものです。
• send_to_existing_only の設定は prioritization の同点動作を変更しません。この設定が true でも false でも、同じ同点およびリトライ動作が適用されます。

注

このエンドポイントでは segment_id パラメーターはサポートされていません。Segmentをターゲットにするには、BrazeダッシュボードのCampaignのターゲットオーディエンス設定でSegmentを設定し、"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の動作に関するドキュメントを参照してください。

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

Campaignの属性オブジェクト

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

ヒント

このエンドポイントのCanvasバージョンをお探しですか？APIトリガー配信を使用したCanvasメッセージの送信をご確認ください。