Notify

POST https://api.pushwoosh.com/messaging/v2/notify

Erstellt und plant eine einzelne Nachricht.

Anfragestruktur

Der Anfragekörper ist eine NotifyRequest mit genau einer von zwei Arten:

• segment: Zielt auf ein Zielgruppensegment nach Segmentcode ab, oder – ohne zuerst ein Segment zu erstellen – auf einen seglang-Ausdruck oder einen strukturierten Filterausdruck.
• transactional: Sendet an eine explizite Liste von HWIDs, Benutzer-IDs, Push-Tokens oder Testgeräten.

Shape

{
  "segment": { ... },      // ODER
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

Feld	Typ	Beschreibung
transaction_id	string	Optional. Idempotenzschlüssel für die Anfrage – funktioniert sowohl mit segment als auch mit transactional. Ein wiederholter Aufruf mit derselben transaction_id innerhalb von 5 Minuten gibt den ursprünglichen message_code zurück, anstatt eine doppelte Nachricht zu senden. Verwenden Sie eine UUID oder einen anderen eindeutigen Wert pro logischem Sendevorgang.

Tipp

Übergeben Sie einen X-Request-ID-Header, um die erstellte Nachricht mit Ihrer Anfrage für eine durchgängige Nachverfolgung zu korrelieren – siehe Request ID.

Nur der Schlüssel wird geprüft, nicht der Payload

Die Deduplizierung erfolgt allein auf Basis der transaction_id. Wenn bei einem Wiederholungsversuch dieselbe transaction_id wiederverwendet wird, aber ein anderer segment- / transactional-Körper gesendet wird, wird dennoch der ursprüngliche message_code zurückgegeben und der neue Körper wird stillschweigend verworfen – er wird nicht mit der ersten Anfrage verglichen. Verwenden Sie eine transaction_id niemals für logisch unterschiedliche Nachrichten wieder.

Tipp

Dies ist derselbe Deduplizierungsmechanismus wie transactionId in der veralteten Messages API, der dasselbe 5-minütige Speicherfenster teilt, sodass eine wiederholte Anfrage sowohl bei /createMessage als auch bei Notify dedupliziert wird. Er steht in keinem Zusammenhang mit dem transaction_id-Attribut bei PW_Conversion-Umsatzereignissen, das Pushwoosh unverändert speichert und nicht zur Deduplizierung verwendet.

NotifySegment

Zielt auf Benutzer ab, die einem Zielgruppensegment oder einem Filterausdruck entsprechen. Legen Sie genau einen der Werte code, expression oder filter_expression fest. Für expression und filter_expression muss vorab kein Segment erstellt werden – der Ausdruck wird nur für diesen Sendevorgang inline ausgewertet.

Wahl zwischen Code und Inline-Ausdrücken

Nur ein gespeichertes Segment, auf das mittels code verwiesen wird, kann die Vorkompilierung für die High-Speed Delivery nutzen. expression und filter_expression werden zur Sendezeit ausgewertet und niemals vorkompiliert.

Feld	Typ	Beschreibung
schedule	Schedule	Wann und wie gesendet werden soll. Erforderlich.
application	string	Anwendungscode.
platforms	array of Platform	Plattformen, auf die die Nachricht abzielt.
code	string	Segmentcode eines im Voraus gespeicherten Segments. Schließt sich gegenseitig mit expression und filter_expression aus.
expression	string	Seglang-Ausdruck, der nur für diesen Sendevorgang ausgewertet wird – kein gespeichertes Segment erforderlich. Schließt sich gegenseitig mit code und filter_expression aus.
filter_expression	FilterExpression	Dieselbe Logik wie expression, jedoch als strukturiertes Objekt anstelle einer Seglang-Zeichenkette. Schließt sich gegenseitig mit code und expression aus. Das FilterExpression-Schema ist nicht öffentlich dokumentiert – fordern Sie es beim Pushwoosh-Support an, wenn Sie die strukturierte Form benötigen.
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger Payload. Schließt sich gegenseitig mit email_payload aus.
email_payload	EmailPayload	E-Mail-Payload.
campaign	string	Kampagnencode, dem diese Nachricht zugeordnet werden soll.
campaign_name	string	Interner Name für diese Nachricht, wird als Zeilentitel in Message History und in deren Export angezeigt. Hat nichts mit campaign oben zu tun. Gruppiert keine Nachrichten und wirkt sich nicht auf die Zustellung aus. Maximal 255 Zeichen, wird gekürzt. Weglassen oder leer lassen, damit der Zeilentitel aus dem Inhalt des Payloads selbst stammt.
frequency_capping	FrequencyCapping	Frequenzbegrenzungen pro Benutzer.
send_rate	SendRate	Drosselung für den Sendevorgang.
message_type	MessageType	MESSAGE_TYPE_MARKETING (Standard) oder MESSAGE_TYPE_TRANSACTIONAL. Steuert die Filterung der Kontrollgruppe.
dynamic_content_placeholders	map<string, string>	Ersetzt Platzhalter im Inhalt.
meta_data	object	Frei definierbare Metadaten, die an nachgelagerte Analysen weitergeleitet werden.
use_latest_user_device	bool	Wenn true, wird die Nachricht an das zuletzt aktive Gerät jedes Benutzers (das mit dem neuesten Last Application Open) zugestellt, anstatt an jedes vom Segment erfasste Gerät. Gilt für platforms: Nur Geräte auf diesen Plattformen werden berücksichtigt. Wenn keines davon Last Application Open-Daten hat, wird das erste passende Gerät verwendet, anstatt den Sendevorgang abzubrechen. Standard ist false (an jedes Gerät senden).

Beispiel: An ein Segment senden

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

Sendet an eine explizite Liste von Empfängern.

Feld	Typ	Beschreibung
schedule	Schedule	Erforderlich.
application	string	Anwendungscode.
platforms	array of Platform	Plattformen, auf die die Nachricht abzielt.
test_devices	bool	Wenn true, nur an die Testgeräte der App senden.
hwids	{ "list": [string, ...] }	Nur an diese HWIDs senden.
users	{ "list": [string, ...] }	Nur an diese Benutzer-IDs senden.
push_tokens	{ "list": [string, ...] }	Nur an diese Push-Tokens senden.
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger Payload.
email_payload	EmailPayload	E-Mail-Payload.
return_unknown_identifiers	bool	Wenn true, listet unknown_identifiers in der Antwort die nicht gefundenen Kennungen auf.
use_latest_user_device	bool	Gilt nur, wenn Sie auf users abzielen. Gleiches Verhalten wie bei NotifySegment oben – stellt eine Nachricht pro Benutzer anstatt pro Gerät zu, beschränkt auf platforms. Standard ist false.
campaign, campaign_name, frequency_capping, send_rate, message_type, dynamic_content_placeholders, meta_data		Siehe NotifySegment oben.

test_devices, hwids, users und push_tokens schließen sich gegenseitig aus. Es muss genau einer festgelegt werden.

Beispiel: Transaktional nach Benutzer-IDs

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["user-123", "user-456"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Your order has shipped." } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true,
      "use_latest_user_device": true
    }
  }'

Antwort

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Feld	Typ	Beschreibung
message_code	string	Eindeutiger Nachrichtencode. Verwenden Sie ihn mit /getMessageDetails und den Endpunkten für Nachrichtenstatistiken.
unknown_identifiers	array of string	Kennungen, die im Konto nicht gefunden wurden. Wird nur gefüllt, wenn return_unknown_identifiers: true für die Art transactional festgelegt wurde.

Geteilte Typen

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

Feld	Typ	Beschreibung
at	timestamp	Absoluter Sendezeitpunkt (RFC 3339). Liegt er in der Vergangenheit, wird die Nachricht sofort gesendet. Maximal 14 Tage in der Zukunft.
after	duration	Alternative zu at. Senden nach diesem Versatz von „jetzt“ (z. B. "3600s").
follow_user_timezone	bool	Wenn true, empfängt jedes Gerät die Nachricht zum Zeitpunkt at in seiner lokalen Zeitzone.
past_timezones_behaviour	enum	PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY (Standard), PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND oder PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY. Nur sinnvoll, wenn follow_user_timezone auf true gesetzt ist.

FrequencyCapping

Frequenzbegrenzungen pro Benutzer für Marketing-Sendungen. Um die Begrenzung zu deaktivieren, lassen Sie frequency_capping ganz weg oder senden Sie days: 0 zusammen mit count: 0.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30 oder 0 zum Deaktivieren der Begrenzung): Rückblickfenster. Muss zusammen mit count gesendet werden – wenn einer 0 ist, muss der andere ebenfalls 0 sein; das Senden eines Wertes als 0, während der andere ungleich null ist, gibt 400 zurück.
• count (int, 1 oder höher, oder 0 zum Deaktivieren der Begrenzung): maximale Anzahl von Nachrichten, die innerhalb von days erlaubt sind. Dieselbe Koppelungsregel wie bei days oben.
• exclude (bool): schließt Benutzer, die das Limit bereits erreicht haben, hart aus.
• avoid (bool): vermeidet Benutzer, die das Limit bereits erreicht haben, weich (sie werden weiterhin für die Analytik gezählt).

Wichtig

Das Senden von days und count mit nicht übereinstimmenden Nullwerten (z. B. {"days": 0, "count": 5}) gibt 400 zurück. Diese Validierung ist eine Breaking Change für Notify – Clients, die sich zuvor darauf verlassen haben, dass eine einzelne 0 stillschweigend ignoriert wird, erhalten jetzt stattdessen einen Fehler.

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

Drosselt den Sendevorgang. value ist die Anzahl der Nachrichten pro bucket; ein typischer bucket ist "1s".

Platform-Enum

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER.

MessageType-Enum

• MESSAGE_TYPE_UNSPECIFIED: entspricht MESSAGE_TYPE_MARKETING.
• MESSAGE_TYPE_MARKETING: unterliegt der Filterung durch Kontrollgruppen und der Frequenzbegrenzung.
• MESSAGE_TYPE_TRANSACTIONAL: überspringt die Filterung durch Kontrollgruppen und die Frequenzbegrenzung. Verwenden Sie dies für Bestellbestätigungen, OTPs und ähnliche kritische Abläufe.

Verwandte Themen

Notify Batch

Abbrechen

Payload-Referenz

E-Mail-Payload-Referenz

Migration von v1