Canvas-Nachrichten mit API-getriggerter Zustellung senden

Verwenden Sie diesen Endpunkt, um Canvas-Nachrichten mit API-getriggerter Zustellung zu versenden.

Die API-getriggerte Zustellung ermöglicht es Ihnen, den Inhalt von Nachrichten im Braze-Dashboard zu speichern und gleichzeitig über Ihre API zu bestimmen, wann und an wen eine Nachricht gesendet wird.

Bevor Sie mit diesem Endpunkt Nachrichten versenden können, müssen Sie über eine Canvas-ID verfügen (die beim Erstellen eines Canvas generiert wird).

Voraussetzungen

Um diesen Endpunkt zu verwenden, müssen Sie einen API-Schlüssel mit der Berechtigung canvas.trigger.send generieren.

Rate-Limit

Bei Verwendung von Connected-Audience-Filtern in Ihrer Anfrage wenden wir ein Rate-Limit von 250 Anfragen pro Minute auf diesen Endpunkt an. Andernfalls gilt bei Angabe einer external_id für diesen Endpunkt ein Standard-Rate-Limit von 250.000 Anfragen pro Stunde, das zwischen den in API-Rate-Limits dokumentierten Endpunkten geteilt wird.

Braze-Endpunkte unterstützen die Stapelverarbeitung von API-Anfragen. Eine einzelne Anfrage an die Messaging-Endpunkte kann Folgendes erreichen:

• Bis zu 50 spezifische external_ids, jeweils mit individuellen Nachrichtenparametern
• Ein Zielgruppensegment beliebiger Größe, das in der Anfrage als Connected-Audience-Objekt definiert ist

Braze-Endpunkte unterstützen die Stapelverarbeitung von API-Anfragen. Eine einzelne Anfrage an die Messaging-Endpunkte kann Folgendes erreichen:

• Bis zu 50 spezifische external_ids, jeweils mit individuellen Nachrichtenparametern
• Ein Zielgruppensegment beliebiger Größe, das in der Anfrage als Connected-Audience-Objekt definiert ist

Anfragetext

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
    }],
    ...
}

Anfrageparameter

Beispielanfrage

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

Antwortdetails

Die Antworten der Endpunkte zum Senden von Nachrichten enthalten die dispatch_id der Nachricht, um den Versand zurückverfolgen zu können. Die dispatch_id ist die ID des Nachrichtenversands (eindeutige ID für jede von der Braze-Plattform gesendete „Übertragung“). Weitere Informationen finden Sie unter Verhalten der Dispatch-ID.

Beispiel für eine erfolgreiche Antwort

Der Statuscode 201 könnte den folgenden Antworttext zurückgeben. Wenn der Canvas archiviert, gestoppt oder pausiert ist, wird er nicht über diesen Endpunkt gesendet.

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

Wenn Ihr Canvas archiviert ist, wird folgende notice-Nachricht angezeigt: „The Canvas is archived. Unarchive the Canvas to ensure trigger requests will take effect.“ Wenn Ihr Canvas nicht aktiv ist, wird folgende notice-Nachricht angezeigt: „The Canvas is paused. Resume the Canvas to ensure trigger requests will take effect.“

Wenn Ihre Anfrage auf einen schwerwiegenden Fehler stößt, finden Sie unter Fehler und Antworten den Fehlercode und die Beschreibung.

Hinweise

Beachten Sie Folgendes, wenn Sie API-Aufrufe zum Senden von Canvas-Nachrichten mit API-getriggerter Zustellung durchführen:

• Versand an bestehende Nutzer:innen: Wenn send_to_existing_only auf true gesetzt ist (Standardwert), wird die Nachricht ausschließlich an bereits in Braze vorhandene Nutzer:innen gesendet.
• Neue Nutzer:innen erstellen: Wenn send_to_existing_only auf false gesetzt ist, müssen Sie ein attributes-Objekt angeben. Sollte ein:e Nutzer:in mit der angegebenen ID nicht vorhanden sein, erstellt Braze vor dem Versenden der Nachricht ein Profil mit dieser ID und den entsprechenden Attributen.
• Neue Profile benötigen attributes mit send_to_existing_only: false. Braze führt das Erstellen oder Aktualisieren vor dem Versand aus dem attributes-Objekt im selben Empfänger:innen-Objekt durch. Wenn Sie send_to_existing_only auf false setzen, aber attributes weglassen (oder ein leeres Objekt senden), hydratisiert Braze die Profildaten nicht auf die gleiche Weise, sodass Sie nicht das kombinierte Verhalten „Nutzer:in erstellen oder aktualisieren, dann senden“ erhalten, für das dieses Muster vorgesehen ist.
• E-Mail- und SMS-Adressierung. Für die meisten E-Mail- oder SMS-API-getriggerten Sendungen an Personen, die noch nicht in Braze vorhanden sind, geben Sie die benötigten Zustellungsfelder innerhalb von attributes an (z. B. email oder die Telefon-Attribute, die Ihr Workspace für SMS verwendet). Sie können dort auch die Abo-Gruppen-Mitgliedschaft oder den Abo-Status festlegen, wenn sich der Opt-in-Status im selben Aufruf ändern muss.
• Canvas-Berechtigung. Nachdem das Profil erstellt oder aktualisiert wurde, muss die bzw. der Nutzer:in weiterhin der im Dashboard konfigurierten Zielgruppe des Canvas und den Kanal-Senderegeln entsprechen (z. B. Opt-in für E-Mail), damit Braze die Nachricht sendet.
• Einschränkung bei Nutzer-Aliasen: Das Flag send_to_existing_only kann nicht mit Nutzer-Aliasen verwendet werden. Um an eine:n Nutzer:in zu senden, die bzw. der nur über einen Alias verfügt, muss diese:r Nutzer:in bereits in Braze vorhanden sein.
• Segment-Targeting: Der Parameter segment_id wird für diesen Endpunkt nicht unterstützt. Um ein Segment anzusprechen, konfigurieren Sie das Segment in den Zielgruppeneinstellungen des Canvas im Braze-Dashboard und verwenden Sie broadcast: true oder den Parameter audience mit Connected-Audience-Filtern.
• Kombiniertes Targeting: Wenn Sie sowohl den Parameter recipients angeben als auch ein Zielsegment im Dashboard konfigurieren, wird die Nachricht nur an Nutzerprofile gesendet, die im API-Aufruf angegeben sind und gleichzeitig den Filtern des Segments entsprechen.
• Server-zu-Server-Aufrufe: Wenn Sie Server-zu-Server-Aufrufe durchführen, müssen Sie möglicherweise die entsprechende API-URL auf die Allowlist setzen, falls Sie sich hinter einer Firewall befinden.

Attribute-Objekt für Canvas

Verwenden Sie das Messaging-Objekt attributes, um Attribute und Werte für eine:n Nutzer:in hinzuzufügen, zu erstellen oder zu aktualisieren, bevor Sie über den Endpunkt canvas/trigger/send ein API-getriggertes Canvas senden. Dieser API-Aufruf verarbeitet das Nutzerattribute-Objekt, bevor er das Canvas verarbeitet und sendet. Dadurch wird das Risiko von Problemen, die durch Race-Conditions verursacht werden, minimiert. Standardmäßig können Abo-Gruppen jedoch nicht auf diese Weise aktualisiert werden.

Hinweis

Sie suchen die Campaign-Version dieses Endpunkts? Informieren Sie sich über den Versand von Campaign-Nachrichten mit API-getriggerter Zustellung.