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

このエンドポイントを使用して、API によってトリガーされる配信でキャンバスメッセージを送信します。

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

このエンドポイントでメッセージを送信するには、キャンバスID(キャンバスの構築時に作成されます)が必要です。

前提条件

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

レート制限

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

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

• それぞれに個別のメッセージパラメーターを持つ、最大 50 個の特定の external_ids
• リクエスト内で接続済みオーディエンスオブジェクトとして定義された、あらゆる規模のオーディエンスセグメント

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

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

要求本文:

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) 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' 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) personalization key-value pairs that apply to this user (these 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
      "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 は、次の応答本文を返す可能性があります。キャンバスがアーカイブされたり、停止されたり、一時停止されたりした場合、キャンバスはこのエンドポイントを通過しない。

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

もしあなたのキャンバスがアーカイブされている場合、このnoticeメッセージが表示される：”キャンバスがアーカイブされます。キャンバスのアーカイブを解除して、トリガーリクエストが有効になるようにします。”もしあなたのキャンバスがアクティブでない場合、このnoticeメッセージが表示される：”キャンバスは一時停止されます。キャンバスを再開して、トリガーリクエストが有効になるようにしてください。」

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

考慮事項

APIトリガーによる配信でキャンバスメッセージを送信するAPI呼び出しを行う際には、以下の点を考慮せよ。

• 既存ユーザーへの送信：が（デフォルト値である）trueに設定されているsend_to_existing_only場合、メッセージはBrazeの既存ユーザーにのみ送信される。
• 新規ユーザーの作成：が に設定されているsend_to_existing_onlyfalse場合、オブジェクトattributesを含めなければならない。指定されたIDのユーザーが存在しない場合、BrazeはそのIDと属性でユーザーを作成してからメッセージを送信する。
• ユーザーエイリアスの制限：フラグsend_to_existing_onlyはユーザーエイリアスでは使用できない。エイリアスのみのユーザーに送信するには、そのユーザーが既にBrazeに存在している必要がある。
• セグメントターゲティング：このエンドポイントでは、そのsegment_idパラメータはサポートされていない。セグメントをターゲットにするには、BrazeダッシュボードのBraze キャンバス内にあるターゲットオーディエンス設定でセグメントを設定し、broadcast: trueを使用するか、Connected Audienceフィルターでaudienceパラメータを使用する。
• 複合標的化：パラメータrecipientsを含め、かつダッシュボードでターゲットセグメントを設定した場合、メッセージはAPI呼び出しで指定されたユーザープロファイルのうち、セグメントのフィルターにも一致するものにのみ送信される。
• サーバー間通信：サーバー間通信を行う場合、ファイアウォールの内側にあるなら、適切なAPIのURLを許可リストに追加する必要があるかもしれない。

キャンバスの属性オブジェクト

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