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.

{
  "segment": { ... }       // ODER
  "transactional": { ... }
}

NotifySegment

Zielt auf Benutzer ab, die einem Zielgruppensegment oder 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 Payload. Schließt sich gegenseitig mit `email_payload` aus.
`email_payload`	`EmailPayload`	E-Mail-Payload.
`campaign`	string	Kampagnencode, dem diese Nachricht zugeordnet werden soll.
`frequency_capping`	`FrequencyCapping`	Frequenzbegrenzungen pro Benutzer.
`send_rate`	`SendRate`	Drosselung für den Versand.
`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 gestaltete 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 Payload.
`email_payload`	`EmailPayload`	E-Mail-Payload.
`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 letzten „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. 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 nicht im Konto gefunden wurden. Wird nur ausgefüllt, wenn `return_unknown_identifiers: true` für die `transactional`-Art festgelegt wurde.

Gemeinsame 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). Wenn 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` `true` 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 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 die Obergrenze bereits erreicht haben, hart ausschließen.
avoid (bool): Benutzer, die die Obergrenze bereits erreicht haben, weich vermeiden (sie zählen weiterhin für die Analytik).

SendRate

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

Drosselt den Versand. 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 Frequenzbegrenzung.
MESSAGE_TYPE_TRANSACTIONAL: überspringt die Filterung durch Kontrollgruppen und die Frequenzbegrenzung. Verwenden Sie es für Bestellbestätigungen, OTPs und ähnliche kritische Abläufe.