Nachrichten sofort nur über die API senden

Verwenden Sie diesen Endpunkt, um über die Braze API sofortige Nachrichten an bestimmte Nutzer:innen zu senden.

Wenn Sie ein Segment als Zielgruppe verwenden, wird ein Datensatz Ihrer Anfrage in der Entwicklungskonsole gespeichert.

Wichtig

Wenn die endgültige gerenderte Nutzlast größer ist als die maximal zulässige Größe des entsprechenden Dienstes, wird die Übertragung nicht erfolgreich sein.

Wichtig

Bei der Verwendung dieses Endpunkts für API-Kampagnen muss die Empfängerin bzw. der Empfänger bereits in Braze vorhanden sein, damit die Anfrage erfolgreich ist. Dies gilt bei der Angabe von Nutzer:innen in den Parametern external_user_ids oder user_aliases.

Neue Nutzer:innen mit API-Sends erstellen

Wenn Sie im Rahmen eines API-Sends eine Nutzer:in erstellen müssen, stehen Ihnen zwei Optionen zur Verfügung:

Option 1: /users/track verwenden und anschließend senden

Erstellen Sie zunächst die Nutzer:in über den /users/track-Endpunkt und warten Sie anschließend, bis die Daten übertragen wurden (in der Regel werden einige Minuten empfohlen), bevor Sie den API-only-Sendvorgang starten. Beachten Sie, dass Braze keine Garantie für die Datenverarbeitungszeiten bei /users/track übernimmt. Daher kann es zu Race-Conditions kommen, wenn zwischen diesen Aufrufen nicht genügend Zeit eingeplant wird.

Option 2: Eine API-getriggerte Kampagne oder einen Canvas verwenden

Verwenden Sie eine API-getriggerte Kampagne oder einen Canvas-Workflow. Hiermit können Sie eine Empfänger:in anlegen, falls noch keine vorhanden ist. Diese Option vereinfacht Ihre Backend-Prozesse, erfordert jedoch die Konfiguration einer Kampagne oder eines Canvas im Braze-Dashboard.

Voraussetzungen

Um diesen Endpunkt zu verwenden, müssen Sie einen API-Schlüssel mit der Berechtigung messages.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
• Ein im Braze-Dashboard erstelltes Segment beliebiger Größe, angegeben durch seine segment_id
• Ein Zielgruppensegment beliebiger Größe, das in der Anfrage als Connected-Audience-Objekt definiert ist

Anfragetext

Tipp

Achten Sie darauf, Messaging-Objekte in Ihren Anfragetext aufzunehmen, um Ihre Anfragen zu vervollständigen.

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
{
   // You will need to include at least one of 'segment_id', 'external_user_ids', and 'audience'
   // Including 'segment_id' will send to members of that segment
   // Including 'external_user_ids' and/or 'user_aliases' will send to those users
   // Including both will send to the provided users if they are in the segment
   "broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if no external_user_ids or aliases are provided,
   "external_user_ids": (optional, array of strings) see external user identifier,
   "user_aliases": (optional, array of user alias object) see user alias,
   "segment_id": (optional, string) see segment identifier,
   "audience": (optional, connected audience object) see connected audience,
   "campaign_id": (optional*, string) *required if you wish to track campaign stats (for example, sends, clicks, bounces, etc). see campaign identifier,
   "send_id": (optional, string) see send identifier,
   "override_frequency_capping": (optional, bool) ignore frequency_capping for campaigns, defaults to false,
   "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
   "messages": {
     "android_push": (optional, android push object),
     "apple_push": (optional, apple push object),
     "content_card": (optional, content card object),
     "email": (optional, email object),
     "kindle_push": (optional, kindle/fireOS push object),
     "web_push": (optional, web push object),
     "webhook": (optional, webhook object),
     "whats_app": (optional, WhatsApp object),
     "sms": (optional, SMS object)
   }
 }

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
69
curl --location --request POST 'https://rest.iad-01.braze.com/messages/send' \
--data-raw '{
  "broadcast": "false",
  "external_user_ids": "external_user_identifiers",
  "user_aliases": {
    "alias_name": "example_name",
    "alias_label": "example_label"
  },
  "segment_id": "segment_identifier",
  "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"
        }
      }
    ]
  },
  "campaign_id": "campaign_identifier",
  "send_id": "send_identifier",
  "override_frequency_capping": "false",
  "recipient_subscription_state": "all",
  "messages": {
    "android_push": "(optional, Android Push Object)",
    "apple_push": "(optional, Apple Push Object)",
    "content_card": "(optional, Content Card Object)",
    "email": "(optional, Email Object)",
    "kindle_push": "(optional, Kindle/FireOS Push Object)",
    "web_push": "(optional, Web Push Object)"
  }
}'

Antwortdetails

Die Antworten des Endpunkts zum Nachrichtenversand enthalten die dispatch_id als Referenz auf den Versand der Nachricht. Die dispatch_id ist die ID des Nachrichtenversands, also die eindeutige ID für jede von Braze gesendete „Übertragung“. Weitere Informationen finden Sie unter Verhalten der Dispatch-ID.