Notification par lot

POST https://api.pushwoosh.com/messaging/v2/notify/batch

Envoie plusieurs messages en un seul appel. Chaque élément est un Notify indépendant : il est validé exactement comme une requête Notify autonome et obtient son propre résultat.

Lisez les résultats, pas le code de statut

L’appel lui-même renvoie HTTP 200 tant que l’enveloppe du lot est valide, même si chaque élément a échoué. Un élément en échec ne fait jamais échouer la requête entière. Vérifiez toujours results[] et les compteurs succeeded / failed ; ne considérez pas une réponse 200 comme une confirmation que les messages ont été envoyés.

Ce n'est pas une manière plus rapide d'envoyer

NotifyBatch n’envoie pas les messages plus rapidement qu’un appel direct à Notify. Si votre intégration peut déjà émettre des requêtes simultanément, exécuter Notify dans des threads/workers parallèles offre le même débit — HTTP/2 gère cela par conception. Utilisez NotifyBatch pour des raisons de commodité lorsque votre intégration n’est pas conçue pour la simultanéité, pas pour la vitesse.

Structure de la requête

Forme

{
  "items": [
    {
      "item_id": "caller-defined-id",
      "request": { ... }
    }
  ]
}

Champ	Type	Description
items	tableau de NotifyBatchItem	Requis, de 1 à 500 entrées (limite configurée par le serveur). Les éléments sont traités simultanément ; les résultats sont renvoyés dans l’ordre de la requête, quoi qu’il arrive.

NotifyBatchItem

Champ	Type	Description
item_id	string	ID de corrélation optionnel fourni par l’appelant, renvoyé en écho dans le résultat correspondant. Non utilisé par Pushwoosh autrement.
request	NotifyRequest	Même corps qu’un appel Notify unique — segment ou transactional, transaction_id inclus. Requis.

schedule est toujours requis par élément

Le request de chaque élément a besoin de son propre schedule, exactement comme un appel Notify autonome. L’omettre ne revient pas à un « envoyer maintenant » — l’élément échoue avec une erreur EmptySchedule.

Réessayer un lot est sûr

Définissez transaction_id sur le request de chaque élément. Un appel répété avec le même transaction_id renvoie le même message_code pour cet élément dans la fenêtre de déduplication de 5 minutes décrite sur la page Notify — ainsi, réessayer le lot entier après une erreur réseau ne duplique pas les messages qui ont déjà été envoyés.

Exemple

curl -X POST https://api.pushwoosh.com/messaging/v2/notify/batch \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "order-1001",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-123"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1001-shipped"
          }
        }
      },
      {
        "item_id": "order-1002",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["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",
            "transaction_id": "order-1002-shipped"
          }
        }
      }
    ]
  }'

Réponse

{
  "results": [
    {
      "item_id": "order-1001",
      "index": 0,
      "result": {
        "message_code": "XXXXX-XXXXX-XXXXX",
        "unknown_identifiers": []
      }
    },
    {
      "item_id": "order-1002",
      "index": 1,
      "error": {
        "code": 3,
        "message": "invalid argument",
        "reason": "EmptySchedule",
        "domain": "api.pushwoosh.com"
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}

Champ	Type	Description
results	tableau de NotifyBatchResult	Une entrée par élément demandé, dans l’ordre de la requête.
succeeded	integer	Nombre d’éléments ayant renvoyé un résultat.
failed	integer	Nombre d’éléments ayant renvoyé une erreur.

NotifyBatchResult

Champ	Type	Description
item_id	string	Écho de l’item_id de l’élément de la requête.
index	integer	Position de base zéro de l’élément dans la requête. Utilisez ceci pour corréler les résultats lorsque item_id a été laissé vide.
result	object	Défini lorsque l’élément a réussi — même forme qu’une réponse Notify unique : message_code et unknown_identifiers.
error	NotifyBatchError	Défini lorsque l’élément a échoué.

NotifyBatchError

Champ	Type	Description
code	integer	Code de statut gRPC (google.rpc.Code), par ex. 3 pour INVALID_ARGUMENT.
message	string	Message d’erreur destiné aux développeurs, en anglais.
reason	string	Nom de statut court — la même valeur qu’un appel Notify unique renverrait, par ex. EmptySchedule.
domain	string	Domaine de l’erreur, api.pushwoosh.com.

Erreurs

Les erreurs utilisent l’enveloppe d’erreur standard de gRPC-Gateway : { "code": ..., "message": ..., "details": [...] }. Ce sont des erreurs au niveau de l’enveloppe qui font échouer toute la requête — un élément individuel en échec produit une error par élément dans results[] à la place (voir NotifyBatchError ci-dessus), pas l’une de celles-ci.

Statut HTTP	Condition
400	items est vide.
400	items contient plus que la limite configurée par le serveur (500 par défaut).
400	Il manque request à l’un des éléments.

Exemple

L’envoi de 501 éléments lorsque la limite est de 500 renvoie un statut HTTP 400 :

{
  "code": 3,
  "message": "items must not exceed 500 entries, got 501",
  "details": []
}

Sujets connexes

Notify

Annuler

Référence du payload

Aperçu de l'API de messagerie v2

Migration depuis la v1