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.

{
  "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.

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.

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.
`silent_hours`	`SilentHours`	Optional. Sendet die Nachricht ohne die Ruhezeiten der Anwendung.
`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).
`geo_zone`	`GeoZone`	Optional. Beschränkt die Zielgruppe auf Geräte, deren zuletzt erfasster Standort innerhalb eines Kreises liegt, den Sie in dieser Anfrage definieren. Wird per AND mit `code`, `expression` oder `filter_expression` kombiniert: Ein Gerät muss dem Segment entsprechen und innerhalb des Kreises liegen. Geräte ohne erfassten Standort werden übersprungen. In `NotifyTransactional` nicht verfügbar.
`control_group`	string	Code oder Name einer eigenen Holdout-Gruppe des Versands, die auf diese Nachricht angewendet wird. Sie schränkt nicht ein, welche Kontrollgruppen gelten: Jede aktivierte Kontrollgruppe der Anwendung hält Benutzer von Marketing-Sendungen zurück, unabhängig davon, ob dieses Feld gesetzt ist. Schließt sich mit `holdout_percentage` gegenseitig aus.
`holdout_percentage`	uint32	Zieht diesen Anteil des Segments, `1`–`20`, in eine Kontrollgruppe, die nur für diesen Versand gilt, zusätzlich zu den aktivierten Kontrollgruppen der Anwendung, um die Wirkung einer einzelnen Kampagne zu messen, ohne die gemeinsamen Kontrollgruppen aufzubrauchen. `0` (Standard) deaktiviert sie. Schließt sich mit `control_group` gegenseitig aus.

Geräte, die in die Holdout-Gruppe gezogen wurden, werden auf dieselbe Weise von der Zustellung ausgeschlossen wie durch die Kontrollgruppen der Anwendung. Sie erhalten die Nachricht nicht, und das Tracking-Log erfasst den Ausschluss als Device is in control group. Ein message_type von MESSAGE_TYPE_TRANSACTIONAL überspringt diesen Ausschluss vollständig, genau wie bei den Kontrollgruppen der Anwendung.

Wird holdout_percentage zusammen mit control_group gesetzt oder ist holdout_percentage größer als 20, wird 400 zurückgegeben:

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

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.
`registration_type`	`RegistrationType`	Legt fest, was mit `hwids` geschieht, die noch nicht in Pushwoosh registriert sind. Standard ist `REGISTRATION_TYPE_DEFAULT`, wodurch sie übersprungen werden. Setzen Sie `REGISTRATION_TYPE_FORCE`, um neue E-Mail-Adressen oder Telefonnummern in derselben Anfrage zu registrieren und an sie zu senden.
`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`, `silent_hours`, `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.

An neue E-Mail-Adressen und Telefonnummern senden

Bei E-Mail, SMS, WhatsApp, LINE, Viber und Kakao ist die hwid das Ziel selbst, etwa die E-Mail-Adresse oder die Telefonnummer. Um an eine noch nicht registrierte hwid zu senden, geben Sie sie in hwids an und setzen Sie registration_type auf REGISTRATION_TYPE_FORCE. Pushwoosh registriert sie und stellt die Nachricht in derselben Anfrage zu, sodass Sie vorher keinen separaten Aufruf von /registerDevice oder /registerEmail benötigen.

registration_type funktioniert nur mit hwids. Bei users wird eine unbekannte Benutzer-ID nicht angelegt, unabhängig vom Wert von registration_type.

Geben Sie jede hwid in dem Format an, in dem /registerDevice sie für diesen Kanal speichert:

Kanal	hwid-Format	Beispiel
E-Mail	E-Mail-Adresse	`new.customer@example.com`
SMS	Telefonnummer im internationalen Format	`+14155552671`
WhatsApp	Telefonnummer mit dem Präfix `whatsapp:`	`whatsapp:+14155552671`
Kakao	Telefonnummer mit dem Präfix `kakao:`	`kakao:+821012345678`
Viber	Telefonnummer mit dem Präfix `viber:`. Pushwoosh ergänzt das Präfix, falls es fehlt	`viber:+14155552671`
LINE	LINE-Benutzer-ID	`U4af4980629a1b2c3d4e5f6a7b8c9d0e1`

Behalten Sie die Präfixe whatsapp: und kakao: bei. Ohne sie wird die Nummer als SMS-hwid gelesen. Ist diese Nummer bereits für SMS registriert, findet der Versand die SMS-hwid, die nicht zur Zielplattform passt, und der Empfänger wird übersprungen.

Pushwoosh prüft Telefonnummern nur bei return_unknown_identifiers: true. Dann wird eine SMS-, WhatsApp- oder Kakao-hwid, die keine gültige Telefonnummer ist, nicht registriert und in unknown_identifiers zurückgegeben. Ohne dieses Flag wird der Wert unverändert registriert.

REGISTRATION_TYPE_FORCE registriert keine hwids auf Push-Plattformen, Telegram oder Facebook Messenger, da diese ein Token vom SDK oder vom Messenger benötigen. Eine unbekannte hwid auf diesen Plattformen wird stillschweigend verworfen. Sie erscheint nicht in unknown_identifiers, und es wird nichts an sie gesendet.

Bei WhatsApp öffnet die Registrierung einer Nummer nicht das 24-Stunden-Kundenservicefenster. Eine Nummer, die Ihnen noch nicht geschrieben hat, kann nur eine vorab genehmigte Vorlage erhalten, die in whatsapp.content_id festgelegt ist, keinen frei formulierten whatsapp.content.

Beispiel: An eine neue E-Mail-Adresse senden

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": ["EMAIL"],
      "hwids": { "list": ["new.customer@example.com"] },
      "registration_type": "REGISTRATION_TYPE_FORCE",
      "email_payload": {
        "subject": { "en": "Welcome aboard" },
        "body": "<p>Thanks for signing up!</p>"
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

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 bei einem `transactional`-Versand mit `return_unknown_identifiers: true` oder mit `push_tokens`-Targeting gefüllt. Über `REGISTRATION_TYPE_FORCE` registrierte Kennungen werden nicht aufgeführt.

/getMessageDetails findet eine transactional-Nachricht nicht, die sofort an weniger als 10 Benutzer und weniger als 10 Geräte gesendet wurde, da eine solche Nachricht nicht gespeichert wird. Siehe Sofort an weniger als 10 Empfänger gesendete Nachrichten.

Keine Empfänger gefunden

Bei return_unknown_identifiers: true oder push_tokens-Targeting sucht Pushwoosh jeden Empfänger, bevor die Nachricht erstellt wird. Ist keiner von ihnen registriert, gibt Notify HTTP 400 mit diesem Fehler zurück, und es wird keine Nachricht erstellt:

{
  "code": 9,
  "message": "No recipients found",
  "details": [ ... ]
}

Wird mindestens ein Empfänger gefunden, ist die Anfrage erfolgreich, und die übrigen werden in unknown_identifiers aufgeführt. Um stattdessen an neue E-Mail-Adressen oder Telefonnummern zu senden, setzen Sie registration_type auf REGISTRATION_TYPE_FORCE.

Bei E-Mail werden ungültige Adressen und Adressen mit früherem Bounce vor dieser Prüfung entfernt, ohne in unknown_identifiers aufgeführt zu werden. Bleibt danach keine Adresse übrig, gibt Notify 200 mit einem message_code zurück, es wird jedoch keine Nachricht erstellt und nichts gesendet.

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). Maximal 30 Tage in der Zukunft. Ist `follow_user_timezone` nicht gesetzt oder `false`, wird ein vergangenes `at` durch den Zeitpunkt des Anfrageeingangs ersetzt, sodass die Nachricht sofort an alle gesendet wird. Bei `follow_user_timezone: true` bleibt ein vergangenes `at` unverändert. Siehe den Hinweis unten.
`after`	duration	Alternative zu `at`. Senden nach diesem Versatz von „jetzt“ (z. B. `"3600s"`). Maximal 30 Tage.
`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 oder `best_time_to_send` gesetzt ist.
`best_time_to_send`	timestamp	Optional. Nur für Segment-Versände. Jedes Gerät erhält die Nachricht zu seiner eigenen besten Stunde innerhalb von 24 Stunden ab diesem Zeitpunkt. Geräte ohne beste Stunde erhalten sie zum Datum und zur Uhrzeit von `at` / `after` in ihrer lokalen Zeitzone. Siehe Beste Sendezeit.

Beste Sendezeit

best_time_to_send ist das API-Gegenstück zur Option Beste Zeit im Control Panel. at / after legt den Fallback für Geräte fest, für die nicht genug Daten für eine beste Stunde vorliegen. Pushwoosh nimmt Datum und Uhrzeit von at / after in UTC und stellt den Fallback zu diesem Datum und dieser Uhrzeit in der lokalen Zeitzone jedes Geräts zu, wie bei follow_user_timezone: true. Das geschieht implizit: Lassen Sie follow_user_timezone ungesetzt, da true mit BestTimeToSendWithUserTimezone abgelehnt wird. Im folgenden Beispiel erhalten Geräte ohne beste Stunde die Nachricht am 1. Mai um 18:00 Uhr Ortszeit. Wo diese Ortszeit beim Start des Versands bereits verstrichen ist, gilt past_timezones_behaviour.

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

Pushwoosh lehnt die Anfrage mit 400 ab, sofern nicht alle folgenden Bedingungen erfüllt sind:

Die Anfrage verwendet die Art segment. transactional-Versände unterstützen best_time_to_send nicht.
follow_user_timezone ist nicht gesetzt oder false.
Der Sendezeitpunkt aus at / after liegt in der Zukunft. Ein vergangenes at, after: "0s" oder ein weggelassenes after gelten als „jetzt senden“ und werden abgelehnt.
best_time_to_send liegt nicht vor der nächsten vollen Stunde und nicht mehr als 30 Tage in der Zukunft. Der Wert wird auf die volle Stunde abgerundet.
Der Sendezeitpunkt aus at / after liegt nicht später als best_time_to_send plus 24 Stunden.

Der reason des Fehlers (im Detail ErrorInfo) nennt die fehlgeschlagene Prüfung:

`reason`	Ursache
`BestTimeToSendWithUserTimezone`	`follow_user_timezone` ist `true`.
`BestTimeToSendTooEarly`	`best_time_to_send` liegt vor der nächsten vollen Stunde.
`BestTimeToSendTooFarInFuture`	`best_time_to_send` liegt mehr als 30 Tage in der Zukunft.
`SendDateAfterBestTimeToSend`	`at` / `after` liegt später als `best_time_to_send` plus 24 Stunden.
`BestTimeToSendNotAllowed`	`best_time_to_send` ist bei einem `transactional`-Versand gesetzt.
`BestTimeToSendWithSendNow`	`at` / `after` ergibt „jetzt“ (vergangenes `at` oder `after` gleich null).

GeoZone

Ein einmaliger Kreis für geo_zone, der direkt in der Anfrage definiert wird. Es handelt sich nicht um eine gespeicherte Geozone: Geo-Kampagnen und die Geozonen-API sind nicht beteiligt, und in der Anwendung wird nichts gespeichert.

{ "lat": 40.7128, "lng": -74.006, "range": 500 }

Feld	Typ	Beschreibung
`lat`	double	Breitengrad des Kreismittelpunkts in Grad. Erforderlich.
`lng`	double	Längengrad des Kreismittelpunkts in Grad. Erforderlich.
`range`	double	Kreisradius in Metern. Erforderlich.

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).

SendRate

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

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

SilentHours

{ "avoid": true }

Marketing-Nachrichten berücksichtigen standardmäßig die Ruhezeiten der Anwendung: Während der Ruhezeit werden sie bis zu deren Ende zurückgehalten oder nicht gesendet, je nach den Einstellungen des Kanals. Setzen Sie avoid auf true, um diese Nachricht auch während der Ruhezeit zu senden. Nachrichten mit message_type MESSAGE_TYPE_TRANSACTIONAL werden nie durch Ruhezeiten zurückgehalten und benötigen dieses Feld daher nicht.

Platform-Enum

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

RegistrationType-Enum

REGISTRATION_TYPE_DEFAULT: überspringt Kennungen, die nicht in Pushwoosh registriert sind. Standard.
REGISTRATION_TYPE_NONE: sendet an jede aufgeführte hwid, ohne ein Gerät dafür zu speichern.
REGISTRATION_TYPE_FORCE: registriert jede unbekannte hwid als Gerät im Zielkanal und sendet dann an sie. Gilt für E-Mail, SMS, WhatsApp, LINE, Viber und Kakao.

MessageType-Enum

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