Skip to content

API トリガー配信経由でキャンバスメッセージを送信

post

/canvas/trigger/send

core エンドポイント

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

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

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

See me in Postman

前提条件

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

レート制限

要求本文:

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,
  "canvas_entry_properties": (optional, object) personalization key-value pairs that will 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 will send 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,
      "canvas_entry_properties": (optional, object) personalization key-value pairs that will apply to this user (these key-value pairs will override any keys that conflict with the parent `canvas_entry_properties`)
      "send_to_existing_only": (optional, boolean) defaults to true, can't be used with user aliases
      "attributes": (optional, object) fields in the attributes object will 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 will be overwritten
    }],
    ...
}

リクエストパラメーター

サーバー間の呼び出しに API を使用する顧客には、ファイアウォールの内側にある場合は、適切な API URL を許可リストに追加する必要が生じることがあります。

例のリクエスト

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",
  "canvas_entry_properties": {"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 メッセージが表示されます。”キャンバスは一時停止されます。キャンバスを再開して、トリガーリクエストが有効になるようにしてください。」

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

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

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

Github   GitHub でこのページを編集
「このページはどの程度役に立ちましたか?」
New Stuff!