Versenden von Nachrichten über die REST API

Sie können Nachrichten in Echtzeit über zwei verschiedene Braze-Endpunkte von Ihrem Backend aus versenden. Jeder hat eine andere Anfragestruktur: Einer erfordert den vollständigen Nachrichteninhalt in der Anfrage, der andere erfordert eine Campaign-ID und sendet den im Dashboard definierten Inhalt.

Dieser Ansatz funktioniert mit jedem von der API unterstützten Messaging-Kanal (WhatsApp, E-Mail, SMS, Push, Content Cards, Webhooks und mehr).

Zwei Möglichkeiten zum Versenden

Ausführliche Informationen zu Anfragen und Antworten finden Sie in den Endpunkt-Referenzen Nachrichten sofort senden (nur API) und Campaigns über API-gesteuerte Zustellung senden.

Option 1: Senden mit Nachrichteninhalt in der Anfrage (/messages/send)

Verwenden Sie diesen Endpunkt, wenn Sie den vollständigen Nachrichteninhalt in der API-Anfrage angeben möchten. Sie müssen ein messages-Objekt einfügen (zum Beispiel messages.whats_app, messages.email oder messages.sms). Sie können campaign_id weglassen, um ohne Campaign-Tracking zu senden, oder eine API-Campaign-ID und message_variation_id in jede Nachricht einfügen, um Sendungen im Dashboard zu verfolgen (weitere Informationen finden Sie in der Endpunkt-Referenz).

Erforderlich: API-Schlüssel mit der Berechtigung messages.send.

Wichtig

Alle Empfänger:innen in external_user_ids müssen bereits in Braze vorhanden sein. Um Nutzer:innen im Rahmen eines Versands zu erstellen, verwenden Sie zunächst /users/track oder nutzen Sie Option 2 (API-gesteuerte Campaign).

Beispiel: WhatsApp-Template-Nachricht

1
2
3
POST YOUR_REST_ENDPOINT/messages/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "external_user_ids": ["user123"],
  "messages": {
    "whats_app": {
      "app_id": "YOUR_APP_ID",
      "subscription_group_id": "YOUR_WHATSAPP_SUBSCRIPTION_GROUP_ID",
      "message_type": "template_message",
      "message": {
        "template_name": "new_message_received",
        "template_language_code": "en_US"
      }
    }
  }
}

Die vollständige Spezifikation des WhatsApp-Objekts finden Sie unter WhatsApp-Objekt.

Hinweis

Der Endpunkt /messages/send unterstützt ausschließlich WhatsApp-Templates mit TEXT- oder IMAGE-Headern. Für die Header-Typen DOCUMENT, VIDEO oder andere Medien verwenden Sie den API-gesteuerten Campaign-Endpunkt oder das Braze-Dashboard.

Beispiel: E-Mail

1
2
3
4
5
6
7
8
9
10
11
{
  "external_user_ids": ["user123"],
  "messages": {
    "email": {
      "app_id": "YOUR_APP_ID",
      "subject": "Your order has shipped",
      "from": "[email protected]",
      "body": "<p>Your order #12345 is on its way.</p>"
    }
  }
}

Für andere Kanäle siehe Messaging-Objekte.

Option 2: Eine Campaign mit Inhalten im Dashboard triggern (/campaigns/trigger/send)

Verwenden Sie diesen Endpunkt, wenn der Nachrichteninhalt im Braze-Dashboard erstellt wird (API-gesteuerte Campaign). Sie senden eine erforderliche campaign_id und Empfänger:innen; Sie senden kein messages-Objekt.

Erforderlich: API-Schlüssel mit der Berechtigung campaigns.trigger.send.

1. Schritt: Eine API-gesteuerte Campaign erstellen

1. Gehen Sie im Braze-Dashboard zu Messaging > Campaigns.
2. Wählen Sie Kampagne erstellen und dann API-gesteuerte Kampagne (nicht „API-Kampagne“).
3. Fügen Sie Ihren Messaging-Kanal hinzu (WhatsApp, E-Mail, SMS usw.) und erstellen Sie den Nachrichteninhalt im Dashboard.
4. Notieren Sie sich die Campaign-ID (und die Sende-ID, falls Sie mehrere Nachrichtenvarianten verwenden). Sie werden diese in der API-Anfrage verwenden.

Weitere Informationen zum Erstellen von API-gesteuerten Campaigns finden Sie unter API-gesteuerte Zustellung.

2. Schritt: Die Campaign über die API triggern

Senden Sie eine POST-Anfrage an /campaigns/trigger/send mit campaign_id und recipients (oder broadcast/audience). Fügen Sie kein messages-Objekt ein – der Inhalt stammt aus der Campaign.

1
2
3
POST YOUR_REST_ENDPOINT/campaigns/trigger/send
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
7
8
{
  "campaign_id": "YOUR_CAMPAIGN_ID",
  "recipients": [
    {
      "external_user_id": "user123"
    }
  ]
}

Den vollständigen Anfragetext (einschließlich trigger_properties, send_to_existing_only, attributes usw.) finden Sie in der Endpunkt-Referenz Campaigns über API-gesteuerte Zustellung senden.

Integration überprüfen

1. Senden Sie eine Anfrage über eine der oben genannten Optionen und geben Sie Ihre eigene Nutzer-ID als Empfänger:in an.
2. Bestätigen Sie, dass die Nachricht zugestellt wurde.
3. Bei Verwendung von Option 2 überprüfen Sie die Campaign im Braze-Dashboard, um sicherzustellen, dass der Versand aufgezeichnet wurde.

Hinweise

• Nutzen Sie die Personalisierungs-Features von Braze, um Inhalte anzupassen, sofern dies unterstützt wird.
• Stellen Sie sicher, dass Ihr Messaging den geltenden Vorschriften entspricht und die erforderlichen Abmeldeoptionen sowie Datenschutzhinweise enthält.
• Weitere Endpunkte (Zeitplan, Canvas-Trigger usw.) finden Sie unter Messaging-Endpunkte.