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でも、同じ同点およびリトライ動作が適用されます。

external_user_idまたはuser_aliasで識別された受信者に対してメール専用Campaignをトリガーし、そのユーザープロファイルに呼び出し時点でメールアドレスがない場合、Brazeは約2時間まで送信をリトライします。これは、ユーザーの作成とメールアドレスの設定が短い間隔で行われる一般的なパターンに対応しています。遅延なく送信するには、recipients[].attributes内にemail属性を含めて、トリガーと同じ呼び出しでアドレスを設定してください。

注

このエンドポイントでは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メッセージの送信をご確認ください。