Campaign-Nachrichten mit API-getriggerter Zustellung versenden

Verwenden Sie diesen Endpunkt, um sofortige, einmalige Nachrichten an bestimmte Nutzer:innen mit Hilfe der API-getriggerten Zustellung zu senden.

Mit der API-getriggerten Zustellung können Sie den Inhalt von Nachrichten innerhalb des Braze-Dashboards unterbringen und gleichzeitig über Ihre API festlegen, wann und an wen eine Nachricht gesendet wird.

Wenn Sie ein Segment ansprechen möchten, wird eine Aufzeichnung Ihrer Anfrage in der Entwicklungskonsole gespeichert. Um Nachrichten mit diesem Endpunkt zu versenden, müssen Sie bei der Erstellung einer API-getriggerten Campaign eine Campaign-ID erstellt haben.

Voraussetzungen

Um diesen Endpunkt zu verwenden, müssen Sie einen API-Schlüssel mit der Berechtigung campaigns.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
20
21
22
23
24
25
26
27
28
{
  "campaign_id": (required, string) see campaign identifier,
  "send_id": (optional, string) see send identifier,
  "trigger_properties": (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' sends to only 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 campaign)
    [
      {
      // 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,
      "trigger_properties": (optional, object) personalization key-value pairs that apply to this user (these key-value pairs override any keys that conflict with the parent trigger_properties),
      "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
    }
  ],
  "attachments": (optional, array) array of JSON objects that define the files you need attached, defined by "file_name" and "url",
    [
      {
       "file_name": (required, string) the name of the file you want to attach to your email, excluding the extension (for example, ".pdf"). Attach files up to 2 MB. This is required if you use "attachments",
       "url": (required, string) the corresponding URL of the file you want to attach to your email. The file name's extension is detected automatically from the URL defined, which should return the appropriate "Content-Type" as a response header. This is required if you use "attachments",
      }
    ]
}

Anfrageparameter

Verhalten bei der Empfänger:innen-Auflösung

In diesem Abschnitt wird erläutert, wie Braze ein Nutzerprofil für den Versand auswählt und was passiert, wenn kein Profil ausgewählt wird.

Der Abo-Gruppenstatus einer Nutzer:in kann über den Parameter subscription_groups innerhalb des attributes-Objekts aktualisiert werden. Weitere Einzelheiten finden Sie unter Nutzerattribute-Objekt.

Empfänger:innen-Limits und Profilerstellung

Erfahren Sie mehr darüber, wie Empfänger:innen-Limits und die Profilerstellung für diesen Endpunkt funktionieren.

• Das recipients-Array kann bis zu 50 Objekte enthalten, wobei jedes Objekt einen einzelnen external_user_id-String und ein trigger_properties-Objekt enthält.
• Wenn send_to_existing_only true ist (Standard), sendet Braze die Nachricht nur an bestehende Nutzer:innen.
• Wenn send_to_existing_only false ist und ein attributes-Objekt bereitgestellt wird, erstellt Braze eine neue Nutzer:in, falls noch keine vorhanden ist.
• Neue Profile benötigen attributes mit send_to_existing_only: false. Braze führt die Erstellung oder Aktualisierung 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, fügen Sie die benötigten Zustellungsfelder in attributes ein (z. B. email oder die Telefon-Attribute, die Ihr Workspace für SMS verwendet). Sie können dort auch die Abo-Gruppenmitgliedschaft oder den Abo-Status festlegen, wenn sich der Opt-in-Status im selben Aufruf ändern muss.
• Campaign-Berechtigung. Nachdem das Profil erstellt oder aktualisiert wurde, muss die Nutzer:in weiterhin der Zielgruppe der Campaign im Dashboard und den Kanal-Senderegeln entsprechen (z. B. Opt-in für E-Mail), damit Braze die Nachricht versendet.
• Die Einstellung send_to_existing_only auf false wird für Nutzer-Aliase nicht unterstützt. Neue Nutzer:innen, die nur über einen Alias verfügen, können über diesen Endpunkt nicht erstellt werden. Um an eine Nutzer:in zu senden, die nur über einen Alias verfügt, muss diese bereits in Braze vorhanden sein.

E-Mail-Bezeichner und Priorisierungs-Gleichstände

Wenn Sie Empfänger:innen per E-Mail identifizieren, verwendet Braze prioritization. Braze sendet nur, wenn prioritization ein Profil zurückgibt.

• Wenn Sie email als Bezeichner verwenden, löst Braze die Empfänger:in über prioritization auf.
• Wenn prioritization einen Gleichstand ergibt, sendet Braze nicht.
• Braze sendet, nachdem der Gleichstand aufgelöst wurde und prioritization ein Profil zurückgibt. Wenn beispielsweise Profilaktualisierungen die Sortierfelder einer Nutzer:in ändern, sendet Braze, sobald prioritization ein Profil eindeutig identifizieren kann (siehe Wiederholungsverhalten und send_to_existing_only).
• Braze sendet auch nicht, wenn prioritization keine Profile zurückgibt.

Wiederholungsverhalten und send_to_existing_only

Erfahren Sie, was passiert, wenn prioritization nicht genau ein Profil zurückgibt.

• Wenn prioritization nicht genau ein Nutzerprofil zurückgibt, wiederholt Braze die Auflösung bis zu 40 Mal. Dieses Wiederholungsverhalten ist erwartungsgemäß.
• Die Einstellung send_to_existing_only ändert das Gleichstandsverhalten von prioritization nicht. Dasselbe Gleichstands- und Wiederholungsverhalten gilt unabhängig davon, ob diese Einstellung true oder false ist.

Wenn Sie eine reine E-Mail-Campaign für eine Empfänger:in triggern, die über external_user_id oder user_alias identifiziert wird, und dieses Nutzerprofil zum Zeitpunkt des Aufrufs keine E-Mail-Adresse hat, wiederholt Braze den Versand für bis zu ca. 2 Stunden. Dies deckt das gängige Muster ab, bei dem eine Nutzer:in erstellt und ihre E-Mail-Adresse kurz darauf festgelegt wird. Um ohne Verzögerung zu senden, fügen Sie das email-Attribut in recipients[].attributes ein, damit die Adresse im selben Aufruf wie der Trigger gesetzt wird.

Hinweis

Der Parameter segment_id wird für diesen Endpunkt nicht unterstützt. Um ein Segment anzusprechen, konfigurieren Sie das Segment in den Zielgruppen-Einstellungen der Campaign im Braze-Dashboard und verwenden Sie "broadcast": true, oder nutzen Sie den audience-Parameter mit Connected Audience-Filtern.

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
69
70
71
72
73
74
75
76
curl --location --request POST 'https://rest.iad-01.braze.com/campaigns/trigger/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "campaign_id": "campaign_identifier",
  "send_id": "send_identifier",
  "trigger_properties": "",
  "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": "external_user_identifier",
      "trigger_properties": "",
      "send_to_existing_only": true,
      "attributes": {
        "first_name" : "Alex"
      }
    }
  ],
  "attachments": [
    {
      "file_name" : "YourFileName",
      "url" : "https://exampleurl.com/YourFileName.pdf"
    }
  ]
}'

Antwortdetails

Die Antworten der Endpunkte zum Senden von Nachrichten enthalten die dispatch_id der Nachricht als Referenz zum Zurückverfolgen des Versands. Die dispatch_id ist die ID des Nachrichtenversands – eine eindeutige ID für jede von Braze gesendete Übertragung. Wenn Sie diesen Endpunkt verwenden, erhalten Sie eine einzige dispatch_id für eine gesamte Gruppe von Nutzer:innen. Weitere Informationen zu dispatch_id finden Sie in unserer Dokumentation über das Verhalten der Dispatch-ID.

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

Attribute-Objekt für Campaigns

Braze verfügt über ein Messaging-Objekt namens attributes, mit dem Sie Attribute und Werte für eine Nutzer:in hinzufügen, erstellen oder aktualisieren können, bevor Sie ihr eine API-getriggerte Campaign senden. Verwenden Sie den campaign/trigger/send-Endpunkt, da dieser API-Aufruf das Nutzerattribute-Objekt verarbeitet, bevor er die Campaign verarbeitet und versendet. Dadurch wird das Risiko von Problemen, die durch Race-Conditions verursacht werden, minimiert.

Tipp

Sie suchen die Canvas-Version dieses Endpunkts? Informieren Sie sich über das Versenden von Canvas-Nachrichten mit API-getriggerter Zustellung.