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 : cibler un segment d’audience par code de segment, une expression seglang ou une expression de filtre structurée.
• transactional : envoyer à une liste explicite de hwids, d’ID utilisateur, de jetons push ou d’appareils de test.

Forme

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

Champ	Type	Description
transaction_id	string	Facultatif. 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

Transmettez 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 la charge utile

La déduplication correspond uniquement sur 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 toujours 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’ancienne API Messages, 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.

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. Mutuellement exclusif avec expression et filter_expression.
expression	string	Expression Seglang.
filter_expression	FilterExpression	Expression de filtre structurée (avancé).
payload	Payload	Charge utile Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber. Mutuellement exclusif avec email_payload.
email_payload	EmailPayload	Charge utile d’e-mail.
campaign	string	Code de campagne auquel attribuer ce message.
frequency_capping	FrequencyCapping	Limites de fréquence par utilisateur.
send_rate	SendRate	Limitation pour l’envoi.
message_type	MessageType	MESSAGE_TYPE_MARKETING (par défaut) ou MESSAGE_TYPE_TRANSACTIONAL. Contrôle le filtrage par 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	Lorsque true, livre le message à l’appareil le plus récemment actif de chaque utilisateur (celui avec la dernière ouverture d’application) au lieu de chaque appareil correspondant au segment. Limité à 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 : Envoyer à 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, envoyer uniquement aux appareils de test de l’application.
hwids	{ "list": [string, ...] }	Envoyer uniquement à ces hwids.
users	{ "list": [string, ...] }	Envoyer uniquement à ces ID utilisateur.
push_tokens	{ "list": [string, ...] }	Envoyer uniquement à ces jetons push.
payload	Payload	Charge utile Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber.
email_payload	EmailPayload	Charge utile 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. Même comportement que dans NotifySegment ci-dessus — livre un message par utilisateur au lieu d’un par appareil, limité à platforms. La valeur par défaut est false.
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

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

Planification

{
  "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. 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 complètement 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. 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 days. Même règle de couplage que days ci-dessus.
• exclude (bool) : exclure strictement 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).

Important

L’envoi de days et count avec des zéros non concordants (par ex. {"days": 0, "count": 5}) renvoie 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 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, 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 par groupe de contrôle et à la limitation de fréquence.
• MESSAGE_TYPE_TRANSACTIONAL : ignore le filtrage par 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

Notifier par lot

Annuler

Référence de la charge utile

Référence de la charge utile d'e-mail

Migration depuis v1