# 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`](#notifysegment): Zielt auf ein Zielgruppensegment nach Segmentcode, einem [seglang](/de/developer/api-reference/segmentation-filters-api/segmentation-language/)-Ausdruck oder einem strukturierten Filterausdruck ab.
- [`transactional`](#notifytransactional): Sendet an eine explizite Liste von HWIDs, Benutzer-IDs, Push-Tokens oder Testgeräten.
```json title="Form"
{
"segment": { ... } // ODER
"transactional": { ... }
}
```
## NotifySegment
Zielt auf Benutzer ab, die einem Zielgruppensegment oder Filterausdruck entsprechen.
| Feld | Typ | Beschreibung |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Wann und wie gesendet werden soll. Erforderlich. |
| `application` | string | [Anwendungscode](/de/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | Plattformen, auf die die Nachricht abzielt. |
| `code` | string | [Segmentcode](/de/developer/api-reference/api-identifiers/#segment--filter-code). Schließt sich gegenseitig mit `expression` und `filter_expression` aus. |
| `expression` | string | [Seglang](/de/developer/api-reference/segmentation-filters-api/segmentation-language/)-Ausdruck. |
| `filter_expression` | `FilterExpression` | Strukturierter Filterausdruck (erweitert). |
| `payload` | [`Payload`](/de/developer/api-reference/messaging-api-v2/payload-reference/) | Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber Payload. Schließt sich gegenseitig mit `email_payload` aus. |
| `email_payload` | [`EmailPayload`](/de/developer/api-reference/messaging-api-v2/email-payload-reference/) | E-Mail-Payload. |
| `campaign` | string | [Kampagnencode](/de/developer/api-reference/api-identifiers/#campaign-code), dem diese Nachricht zugeordnet werden soll. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Frequenzbegrenzungen pro Benutzer. |
| `send_rate` | [`SendRate`](#sendrate) | Drosselung für den Versand. |
| `message_type` | [`MessageType`](#messagetype-enum) | `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
```bash
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`](#schedule) | Erforderlich. |
| `application` | string | [Anwendungscode](/de/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | 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](/de/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) senden. |
| `users` | `{ "list": [string, ...] }` | Nur an diese [Benutzer-IDs](/de/developer/pushwoosh-knowledge-hub/users-userids/) senden. |
| `push_tokens` | `{ "list": [string, ...] }` | Nur an diese [Push-Tokens](/de/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token) senden. |
| `payload` | [`Payload`](/de/developer/api-reference/messaging-api-v2/payload-reference/) | Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber Payload. |
| `email_payload` | [`EmailPayload`](/de/developer/api-reference/messaging-api-v2/email-payload-reference/) | 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
```bash
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
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| Feld | Typ | Beschreibung |
|---|---|---|
| `message_code` | string | Eindeutiger [Nachrichtencode](/de/developer/api-reference/api-identifiers/#message-code). Verwenden Sie ihn mit [`/getMessageDetails`](/de/developer/api-reference/messages-api/#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
```json
{
"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`.
```json
{ "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
```json
{ "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.
## Verwandte Themen