# Notify
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
Crée et planifie un message unique.
## Structure de la requête
Le corps de la requête est un `NotifyRequest` avec exactement l'un des deux types suivants :
- [`segment`](#notifysegment) : cible un segment d'audience par code de segment, une expression [seglang](/fr/developer/api-reference/segmentation-filters-api/segmentation-language/) ou une expression de filtre structurée.
- [`transactional`](#notifytransactional) : envoie à une liste explicite de hwids, d'ID utilisateur, de jetons push ou d'appareils de test.
```json title="Forme"
{
"segment": { ... } // OU
"transactional": { ... }
}
```
## NotifySegment
Cible les utilisateurs qui correspondent à un segment d'audience ou à une expression de filtre.
| Champ | Type | Description |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Quand et comment envoyer. Requis. |
| `application` | string | [Code d'application](/fr/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | Plateformes ciblées par le message. |
| `code` | string | [Code de segment](/fr/developer/api-reference/api-identifiers/#segment--filter-code). Mutuellement exclusif avec `expression` et `filter_expression`. |
| `expression` | string | Expression [Seglang](/fr/developer/api-reference/segmentation-filters-api/segmentation-language/). |
| `filter_expression` | `FilterExpression` | Expression de filtre structurée (avancé). |
| `payload` | [`Payload`](/fr/developer/api-reference/messaging-api-v2/payload-reference/) | Payload Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Mutuellement exclusif avec `email_payload`. |
| `email_payload` | [`EmailPayload`](/fr/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload d'e-mail. |
| `campaign` | string | [Code de campagne](/fr/developer/api-reference/api-identifiers/#campaign-code) auquel attribuer ce message. |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | Limites de fréquence par utilisateur. |
| `send_rate` | [`SendRate`](#sendrate) | Limitation de débit pour l'envoi. |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING` (par défaut) ou `MESSAGE_TYPE_TRANSACTIONAL`. Contrôle le filtrage du groupe de contrôle. |
| `dynamic_content_placeholders` | map<string, string> | Remplace les espaces réservés dans le contenu. |
| `meta_data` | object | Métadonnées de forme libre transmises aux analyses en aval. |
### Exemple : Envoyer à un segment
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token VOTRE_JETON_API" \
-H "Content-Type: application/json" \
-d '{
"segment": {
"application": "XXXXX-XXXXX",
"platforms": ["IOS", "ANDROID"],
"code": "utilisateurs_actifs",
"payload": {
"content": {
"localized_content": {
"fr": {
"ios": { "body": "Bonjour !" },
"android": { "body": "Bonjour !" }
}
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_MARKETING"
}
}'
```
## NotifyTransactional
Envoie à une liste explicite de destinataires.
| Champ | Type | Description |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | Requis. |
| `application` | string | [Code d'application](/fr/developer/api-reference/api-identifiers/#application-code). |
| `platforms` | array of [`Platform`](#platform-enum) | Plateformes ciblées par le message. |
| `test_devices` | bool | Si `true`, envoie uniquement aux appareils de test de l'application. |
| `hwids` | `{ "list": [string, ...] }` | Envoyer uniquement à ces [hwids](/fr/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid). |
| `users` | `{ "list": [string, ...] }` | Envoyer uniquement à ces [ID utilisateur](/fr/developer/pushwoosh-knowledge-hub/users-userids/). |
| `push_tokens` | `{ "list": [string, ...] }` | Envoyer uniquement à ces [jetons push](/fr/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token). |
| `payload` | [`Payload`](/fr/developer/api-reference/messaging-api-v2/payload-reference/) | Payload Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. |
| `email_payload` | [`EmailPayload`](/fr/developer/api-reference/messaging-api-v2/email-payload-reference/) | Payload d'e-mail. |
| `return_unknown_identifiers` | bool | Lorsque `true`, la réponse `unknown_identifiers` liste les identifiants qui n'ont pas été trouvés. |
| `use_latest_user_device` | bool | S'applique uniquement lorsque vous ciblez des `users`. Lorsque `true`, le message est livré à l'appareil le plus récemment actif de chaque utilisateur — celui avec la dernière ouverture d'application — au lieu de tous les appareils liés à cet ID utilisateur. La valeur par défaut est `false` (envoyer à chaque appareil). |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | Voir `NotifySegment` ci-dessus. |
`test_devices`, `hwids`, `users` et `push_tokens` sont mutuellement exclusifs. Un seul doit être défini.
### Exemple : Transactionnel par ID utilisateur
```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
-H "Authorization: Token VOTRE_JETON_API" \
-H "Content-Type: application/json" \
-d '{
"transactional": {
"application": "XXXXX-XXXXX",
"platforms": ["IOS", "ANDROID"],
"users": { "list": ["user-123", "user-456"] },
"payload": {
"content": {
"localized_content": {
"fr": { "ios": { "body": "Votre commande a été expédiée." } }
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_TRANSACTIONAL",
"return_unknown_identifiers": true,
"use_latest_user_device": true
}
}'
```
## Réponse
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| Champ | Type | Description |
|---|---|---|
| `message_code` | string | [Code de message](/fr/developer/api-reference/api-identifiers/#message-code) unique. Utilisez-le avec [`/getMessageDetails`](/fr/developer/api-reference/messages-api/#getmessagedetails) et les points de terminaison des statistiques de message. |
| `unknown_identifiers` | array of string | Identifiants non trouvés sur le compte. Rempli uniquement lorsque `return_unknown_identifiers: true` a été défini sur le type `transactional`. |
## Types partagés
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| Champ | Type | Description |
|---|---|---|
| `at` | timestamp | Heure d'envoi absolue (RFC 3339). Si dans le passé, le message est envoyé immédiatement. Maximum 14 jours dans le futur. |
| `after` | duration | Alternative à `at`. Envoyer après ce décalage par rapport à "maintenant" (par ex. `"3600s"`). |
| `follow_user_timezone` | bool | Lorsque `true`, chaque appareil reçoit le message à `at` dans son fuseau horaire local. |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY` (par défaut), `PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND`, ou `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`. Significatif uniquement lorsque `follow_user_timezone` est `true`. |
### FrequencyCapping
Limites de fréquence par utilisateur pour les envois marketing. Pour désactiver la limitation, omettez entièrement `frequency_capping`, ou envoyez `days: 0` avec `count: 0`.
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days` (int, 1–30, ou `0` pour désactiver la limitation) : fenêtre de rétrospection. Doit être envoyé avec `count` — si l'un est `0`, l'autre doit aussi être `0` ; envoyer l'un à `0` alors que l'autre est non nul renvoie `400`.
- `count` (int, 1 ou plus, ou `0` pour désactiver la limitation) : nombre maximum de messages autorisés dans les `days`. Même règle de couplage que `days` ci-dessus.
- `exclude` (bool) : exclure de manière stricte les utilisateurs qui ont déjà atteint la limite.
- `avoid` (bool) : éviter de manière souple les utilisateurs qui ont déjà atteint la limite (ils comptent toujours pour les analyses).
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
Limite le débit de l'envoi. `value` est le nombre de messages par `bucket` ; un `bucket` typique est `"1s"`.
### Énumération Platform
`IOS`, `ANDROID`, `OSX`, `WINDOWS`, `AMAZON`, `SAFARI`, `CHROME`, `FIREFOX`, `IE`, `EMAIL`, `BAIDU_ANDROID`, `HUAWEI_ANDROID`, `SMS`, `WEB`, `KAKAO`, `TELEGRAM`, `LINE`, `WHATS_APP`, `VIBER`.
### Énumération MessageType
- `MESSAGE_TYPE_UNSPECIFIED` : équivalent à `MESSAGE_TYPE_MARKETING`.
- `MESSAGE_TYPE_MARKETING` : soumis au filtrage du groupe de contrôle et à la limitation de fréquence.
- `MESSAGE_TYPE_TRANSACTIONAL` : ignore le filtrage du groupe de contrôle et la limitation de fréquence. À utiliser pour les confirmations de commande, les OTP et les flux critiques similaires.
## Sujets connexes