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, einem seglang-Ausdruck oder einem strukturierten Filterausdruck ab.
• transactional: sendet an eine explizite Liste von HWIDs, Benutzer-IDs, Push-Token oder Testgeräten.

Shape

{
  "segment": { ... },      // OR
  "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 Wert, der pro logischem Sendevorgang eindeutig ist.

Tipp

Übergeben Sie einen X-Request-ID-Header, um die erstellte Nachricht mit Ihrer Anfrage für eine End-to-End-Verfolgung zu korrelieren – siehe Request ID.

Nur der Schlüssel wird geprüft, nicht die Nutzlast

Die Deduplizierung erfolgt ausschließlich über die 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 sich dasselbe 5-minütige Speicherfenster teilt, sodass eine wiederholte Anfrage sowohl bei /createMessage als auch bei Notify dedupliziert wird. Es besteht kein 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.

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. Schließt sich gegenseitig mit expression und filter_expression aus.
expression	string	Seglang-Ausdruck.
filter_expression	FilterExpression	Strukturierter Filterausdruck (erweitert).
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber-Nutzlast. Schließt sich gegenseitig mit email_payload aus.
email_payload	EmailPayload	E-Mail-Nutzlast.
campaign	string	Kampagnencode, dem diese Nachricht zugeordnet werden soll.
frequency_capping	FrequencyCapping	Häufigkeitsbegrenzungen 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	Freiform-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 gefundene Gerät. Gilt für platforms: Nur Geräte auf diesen Plattformen werden berücksichtigt, und wenn keines 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-Token senden.
payload	Payload	Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber-Nutzlast.
email_payload	EmailPayload	E-Mail-Nutzlast.
return_unknown_identifiers	bool	Wenn true, listet unknown_identifiers 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 anstelle von einer pro Gerät zu, beschränkt auf platforms. Standard ist false.
campaign, 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 eines 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 den Endpunkten /getMessageDetails und Nachrichtenstatistiken.
unknown_identifiers	array of string	Kennungen, die im Konto nicht gefunden wurden. Wird nur ausgefü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	Absolute Sendezeit (RFC 3339). Liegt sie 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 zur Zeit 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

Häufigkeitsbegrenzungen 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 eines 0 ist, muss das andere ebenfalls 0 sein; wird eines als 0 gesendet, während das andere ungleich null ist, wird 400 zurückgegeben.
• count (int, 1 oder höher, oder 0 zum Deaktivieren der Begrenzung): maximale Anzahl von Nachrichten innerhalb von days. Dieselbe Kopplungsregel 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, sanft (sie zählen weiterhin für die Analysen).

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.

MessageType-Enum

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

Verwandte Themen

Notify Batch

Cancel

Nutzlast-Referenz

E-Mail-Nutzlast-Referenz

Migration von v1