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 :

• segment : cible un segment d’audience par code de segment, ou — sans créer de segment au préalable — une expression seglang ou une expression de filtre structurée.
• transactional : envoie à une liste explicite de HWID, d’ID utilisateur, de jetons push ou d’appareils de test.

Shape

{
  "segment": { ... },      // OU
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

Champ	Type	Description
transaction_id	string	Optionnel. Clé d’idempotence pour la requête — fonctionne avec segment et transactional. Un appel répété avec le même transaction_id dans les 5 minutes renvoie le message_code original au lieu d’envoyer un message en double. Utilisez un UUID ou une autre valeur unique par envoi logique.

Conseil

Passez un en-tête X-Request-ID pour corréler le message créé avec votre requête pour un suivi de bout en bout — voir ID de requête.

Seule la clé est vérifiée, pas le payload

La déduplication se base uniquement sur le transaction_id. Si une nouvelle tentative réutilise le même transaction_id mais envoie un corps segment / transactional différent, le message_code original est tout de même renvoyé et le nouveau corps est silencieusement ignoré — il n’est pas comparé à la première requête. Ne réutilisez jamais un transaction_id pour des messages logiquement différents.

Conseil

C’est le même mécanisme de déduplication que transactionId sur l’API Messages héritée, partageant la même fenêtre de stockage de 5 minutes, donc une requête réessayée est dédupliquée à la fois sur /createMessage et Notify. Il n’est pas lié à l’attribut transaction_id sur les événements de revenus PW_Conversion, que Pushwoosh stocke tel quel et n’utilise pas pour la déduplication.

NotifySegment

Cible les utilisateurs qui correspondent à un segment d’audience ou à une expression de filtre. Définissez exactement l’un des champs suivants : code, expression ou filter_expression. Pour expression et filter_expression, aucun segment ne doit être créé au préalable — l’expression est évaluée en ligne pour cet envoi uniquement.

Choisir entre le code et les expressions en ligne

Seul un segment enregistré référencé par code peut utiliser la précompilation high-speed delivery. expression et filter_expression sont évalués au moment de l’envoi et ne sont jamais précompilés.

Champ	Type	Description
schedule	Schedule	Quand et comment envoyer. Requis.
application	string	Code d’application.
platforms	array of Platform	Plateformes ciblées par le message.
code	string	Code de segment d’un segment enregistré à l’avance. Mutuellement exclusif avec expression et filter_expression.
expression	string	Expression Seglang, évaluée pour cet envoi uniquement — aucun segment enregistré n’est requis. Mutuellement exclusif avec code et filter_expression.
filter_expression	FilterExpression	La même logique que expression, sous forme d’objet structuré au lieu d’une chaîne seglang. Mutuellement exclusif avec code et expression. Le schéma FilterExpression n’est pas documenté publiquement — demandez-le au support de Pushwoosh si vous avez besoin de la forme structurée.
payload	Payload	Payload Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger. Mutuellement exclusif avec email_payload.
email_payload	EmailPayload	Payload d’e-mail.
campaign	string	Code de campagne auquel attribuer ce message.
campaign_name	string	Nom interne de ce message, affiché comme le titre de la ligne dans Message History et dans son export. Sans rapport avec campaign ci-dessus. Ne regroupe pas les messages et n’affecte pas la livraison. Max 255 caractères, tronqué. Omettez-le ou laissez-le vide pour que le titre de la ligne provienne du contenu du payload lui-même.
frequency_capping	FrequencyCapping	Limites de fréquence par utilisateur.
send_rate	SendRate	Limitation du débit pour l’envoi.
message_type	MessageType	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 placeholders dans le contenu.
meta_data	object	Métadonnées de forme libre transmises aux analyses en aval.
use_latest_user_device	bool	Si true, livre le message à l’appareil le plus récemment actif de chaque utilisateur (celui avec la dernière ouverture d’application la plus récente) au lieu de chaque appareil correspondant au segment. Limité aux platforms : seuls les appareils sur ces plateformes sont pris en compte, et si aucun n’a de données de dernière ouverture d’application, le premier appareil correspondant est utilisé au lieu d’annuler l’envoi. La valeur par défaut est false (envoyer à chaque appareil).

Exemple : Envoi à un segment

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

Envoie à une liste explicite de destinataires.

Champ	Type	Description
schedule	Schedule	Requis.
application	string	Code d’application.
platforms	array of Platform	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 HWID.
users	{ "list": [string, ...] }	Envoyer uniquement à ces ID utilisateur.
push_tokens	{ "list": [string, ...] }	Envoyer uniquement à ces jetons push.
payload	Payload	Payload Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger.
email_payload	EmailPayload	Payload d’e-mail.
return_unknown_identifiers	bool	Si true, la liste unknown_identifiers de la réponse contient les identifiants qui n’ont pas été trouvés.
use_latest_user_device	bool	S’applique uniquement lorsque vous ciblez des users. Même comportement que dans NotifySegment ci-dessus — livre un message par utilisateur au lieu d’un par appareil, limité aux platforms. La valeur par défaut est false.
campaign, campaign_name, 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

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
    }
  }'

Réponse

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Champ	Type	Description
message_code	string	Code de message unique. Utilisez-le avec /getMessageDetails et les points de terminaison de 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

{
  "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 elle est 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	Si true, chaque appareil reçoit le message à l’heure 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. N’a de sens que si 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.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30, ou 0 pour désactiver la limitation) : fenêtre de temps à analyser. 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 une erreur 400.
• count (int, 1 ou plus, ou 0 pour désactiver la limitation) : nombre maximum de messages autorisés pendant la période 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 sont toujours comptabilisés dans les analyses).

Important

Envoyer days et count avec des zéros non concordants (par ex. {"days": 0, "count": 5}) renvoie une erreur 400. Cette validation est un changement radical pour Notify — les clients qui se fiaient auparavant à un 0 seul étant ignoré silencieusement recevront maintenant une erreur.

SendRate

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

Limite le débit de l’envoi. value correspond au nombre de messages par bucket ; un bucket typique est "1s".

Énumération Platform

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

É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 autres flux critiques similaires.

Articles connexes

Notify batch

Cancel

Référence du payload

Référence du payload d'e-mail

Migration depuis la v1