Benachrichtigen

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

Erstellt und plant eine einzelne Nachricht.

Anfragestruktur

Der Anfragetext ist ein 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-Tokens 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-Nachverfolgung zu korrelieren – siehe Request ID.

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

Die Deduplizierung erfolgt allein über die transaction_id. Wenn bei einem Wiederholungsversuch dieselbe transaction_id wiederverwendet wird, aber ein anderer segment- / transactional-Body gesendet wird, wird trotzdem der ursprüngliche message_code zurückgegeben und der neue Body 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 über /createMessage als auch über Notify dedupliziert wird. Es hat nichts mit dem transaction_id-Attribut bei PW_Conversion-Umsatzereignissen zu tun, das Pushwoosh unverändert speichert und nicht zur Deduplizierung verwendet.

NotifySegment

Zielt auf Benutzer ab, die mit einem Zielgruppensegment oder einem Filterausdruck übereinstimmen.

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	Frei-form Metadaten, die an nachgelagerte Analysen weitergeleitet werden.

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-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. Wenn true, wird die Nachricht an das zuletzt aktive Gerät jedes Benutzers zugestellt – das mit dem neuesten „Last Application Open“ – anstatt an alle Geräte, die mit dieser Benutzer-ID verknüpft sind. Standard ist false (an jedes Gerät senden).
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. Genau eines muss gesetzt 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 gefüllt, wenn return_unknown_identifiers: true bei der transactional-Art gesetzt 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. Nach diesem Versatz von “jetzt” senden (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 einer 0 ist, muss der andere ebenfalls 0 sein; das Senden von einem 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 Paarungsregel wie bei days oben.
• exclude (bool): Benutzer, die das Limit bereits erreicht haben, hart ausschließen.
• avoid (bool): Benutzer, die das Limit bereits erreicht haben, weich vermeiden (sie zählen trotzdem zur Analyse).

Wichtig

Das Senden von days und count mit nicht übereinstimmender Nullheit (z. B. {"days": 0, "count": 5}) gibt 400 zurück. Diese Validierung ist eine grundlegende Änderung an 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, BAIDU_ANDROID, 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

Abbrechen

Payload-Referenz

E-Mail-Payload-Referenz

Migration von v1