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

このエンドポイントを使用して、APIトリガー配信でCanvasメッセージを送信します。

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

このエンドポイントでメッセージを送信するには、Canvas ID（Canvasの構築時に作成されます）が必要です。

前提条件

このエンドポイントを使用するには、canvas.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
{
  "canvas_id": (required, string) see Canvas identifier,
  "context": (optional, object) Canvas context properties 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' will only send to 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 Canvas)
    [{
      // 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,
      "context": (optional, object) Canvas context properties for this user; key-value pairs override any keys that conflict with the parent `context`,
      "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
    }],
    ...
}

リクエストパラメーター

リクエスト例

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
curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "canvas_id": "canvas_identifier",
  "context": {"product_name" : "shoes", "product_price" : 79.99},
  "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": "user_identifier",
      "send_to_existing_only": true,
      "attributes": {
          "first_name" : "Alex"
      }
    }
  ]
}'

レスポンスの詳細

メッセージ送信エンドポイントのレスポンスには、メッセージのディスパッチを参照するためのdispatch_idが含まれます。dispatch_idはメッセージディスパッチのIDです（Brazeプラットフォームから送信される各「送信」に固有のID）。詳細については、ディスパッチIDの動作を参照してください。

成功レスポンスの例

ステータスコード201は、次のレスポンス本文を返す可能性があります。Canvasがアーカイブ、停止、または一時停止されている場合、このエンドポイントを通じてCanvasは送信されません。

1
2
3
4
5
{
  "notice": "The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.",
  "dispatch_id": "example_dispatch_id",
  "message": "success"
}

Canvasがアーカイブされている場合、次のnoticeメッセージが表示されます：「The Canvas is archived. Unarchive the Canvas to ensure trigger requests will take effect.」Canvasがアクティブでない場合、次のnoticeメッセージが表示されます：「The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.」

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

考慮事項

APIトリガー配信を使用してCanvasメッセージを送信するAPI呼び出しを行う際には、以下の点を考慮してください。

• 既存ユーザーへの送信：send_to_existing_onlyがtrue（デフォルト値）に設定されている場合、メッセージはBrazeの既存ユーザーにのみ送信されます。
• 新規ユーザーの作成：send_to_existing_onlyがfalseに設定されている場合、attributesオブジェクトを含める必要があります。指定されたIDのユーザーが存在しない場合、BrazeはそのIDと属性でユーザーを作成してからメッセージを送信します。
• 新規プロファイルにはsend_to_existing_only: falseとattributesが必要です。 Brazeは同じ受信者内のattributesオブジェクトから送信前の作成または更新を実行します。send_to_existing_onlyをfalseに設定してもattributesを省略した場合（または空のオブジェクトを送信した場合）、Brazeは同じ方法でプロファイルデータをハイドレートしないため、このパターンが意図する「ユーザーを作成または更新してから送信する」動作は得られません。
• メールとSMSのアドレス指定： まだBrazeに存在しないユーザーへのメールまたはSMSのAPIトリガー送信のほとんどでは、attributes内に必要な配信フィールド（例：email、またはワークスペースがSMSに使用する電話属性）を含めてください。同じ呼び出しでオプトイン状態を変更する必要がある場合は、サブスクリプショングループのメンバーシップやサブスクリプションステータスもそこで設定できます。
• Canvasの適格性： プロファイルが存在または更新された後も、そのユーザーはCanvasのダッシュボードターゲットオーディエンスとチャネル送信ルール（例：メールのオプトイン済み）に一致する必要があります。一致しない場合、Brazeはメッセージを送信しません。
• ユーザーエイリアスの制限：send_to_existing_onlyフラグはユーザーエイリアスでは使用できません。エイリアスのみのユーザーに送信するには、そのユーザーがすでにBrazeに存在している必要があります。
• Segmentターゲティング：このエンドポイントではsegment_idパラメーターはサポートされていません。Segmentをターゲットにするには、BrazeダッシュボードのCanvasのターゲットオーディエンス設定でSegmentを設定し、broadcast: trueを使用するか、接続オーディエンスフィルターでaudienceパラメーターを使用します。
• 複合ターゲティング：recipientsパラメーターを含め、かつダッシュボードでターゲットSegmentを設定した場合、メッセージはAPI呼び出しで指定されたユーザープロファイルのうち、Segmentのフィルターにも一致するものにのみ送信されます。
• サーバー間通信：サーバー間通信を行う場合、ファイアウォールの内側にいるときは適切なAPI URLを許可リストに追加する必要がある場合があります。

Canvasの属性オブジェクト

メッセージングオブジェクトattributesを使用して、canvas/trigger/sendエンドポイントでAPIトリガーCanvasを送信する前に、ユーザーの属性と値を追加、作成、または更新します。このAPI呼び出しは、Canvasを処理して送信する前にユーザー属性オブジェクトを処理します。これにより、競合によって発生する問題のリスクを最小限に抑えることができます。ただし、デフォルトでは、サブスクリプショングループをこの方法で更新することはできません。

注

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