Skip to content

API 트리거 배달을 사용하여 캔버스 메시지 보내기

post

/canvas/trigger/send

core endpoint

이 엔드포인트를 사용하여 API 트리거 배달을 통해 캔버스 메시지를 전송할 수 있습니다.

API 트리거 전송을 사용하면 메시지 콘텐츠를 Braze 대시보드에 저장하는 동시에 API를 사용하여 메시지를 언제, 누구에게 보낼지 지정할 수 있습니다.

이 엔드포인트로 메시지를 보내려면 먼저 캔버스 ID (캔버스를 만들 때 생성됨)가 있어야 합니다.

See me in Postman

필수 구성 요소

이 엔드포인트를 사용하려면 canvas.trigger.send 권한으로 API 키를 생성해야 합니다.

사용량 제한

요청에 세그먼트 또는 연결된 오디언스를 지정할 때 이 엔드포인트에는 분당 250건의 요청 속도 제한이 적용됩니다. 그렇지 않으면 external_id 을 지정하는 경우 이 엔드포인트는 API 속도 제한에 설명된 대로 /messages/send, /campaigns/trigger/send, /canvas/trigger/send 간에 시간당 250,000건의 요청이 공유되는 기본 속도 제한을 갖습니다.

요청 본문

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 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 호출은 캔버스를 처리하고 전송하기 전에 사용자 속성 개체를 처리합니다. 이렇게 하면 경쟁 조건으로 인한 문제 발생 위험을 최소화할 수 있습니다. 그러나 기본적으로 구독 그룹은 이 방법으로 업데이트할 수 없습니다.

Github   GitHub 에서 이 페이지를 편집합니다.
이 페이지가 얼마나 도움이 되었나요?
New Stuff!