Notifier

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 : ciblez un segment d’audience par code de segment, une expression seglang ou une expression de filtre structurée.
• transactional : envoyez à 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 la charge utile

La déduplication se base 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 de la vitesse d’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 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

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 vrai, envoyer 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	Charge utile Push / SMS / Telegram / Kakao / LINE / WhatsApp / Viber.
email_payload	EmailPayload	Charge utile d’e-mail.
return_unknown_identifiers	bool	Si vrai, 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. Si vrai, 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

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	Si vrai, 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. Pertinent uniquement 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 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 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).

Important

Envoyer 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 comptaient auparavant sur un 0 seul étant ignoré silencieusement recevront maintenant une erreur.

SendRate

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

Limite la vitesse d’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

Annuler

Référence de la charge utile

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

Migration depuis v1