How do I apply Frequency Capping to messages sent via the /createMessage API?

By default, all messages sent using the /createMessage API automatically respect the Global Frequency Capping rules you have configured in your Pushwoosh Control Panel (Settings > Message delivery settings > Frequency capping). You do not need to add any special parameters for this standard behavior.

Applying a Custom, Per-Message Cap

If you want to apply a different, more specific frequency cap for a particular API message, you can use the capping_days and capping_count parameters within the notifications object of your request.

• capping_days: the length of the capping window in days (maximum 30).
• capping_count: the maximum number of pushes that can be sent from this app to a particular device within the capping_days period.

If a message exceeds this custom limit for a device, it will not be sent to that device.

Example Request with Custom Capping:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "YOUR_API_ACCESS_TOKEN",
    "notifications": [
      {
        "send_date": "now",
        "content": "This message has a custom frequency cap.",
        "devices": ["device_hwid"],
        "capping_days": 7,
        "capping_count": 3
      }
    ]
  }
}

In this example, the message will only be sent if the device has received fewer than 3 pushes from this app in the last 7 days.

Important: a custom per-message cap does not switch capping off — the message is still evaluated against, and counted towards, the limits configured in the Control Panel. To ignore those limits you have to ask for it explicitly (see below).

Bypassing or Excluding a Message from Frequency Capping

Two separate parameters are available and they do different things:

• capping_avoid: true — capping is not applied to this particular push, so it is delivered even if the device has already reached its limit.
• capping_exclude: true — this push is not counted towards the capping of future pushes; on its own it does not let a push through a limit that has already been reached.

For critical, must-deliver messages (for example security codes) set both: capping_avoid: true so it is delivered regardless of the limits, and capping_exclude: true so it does not consume the device’s quota for your regular campaigns. Alternatively, mark the send as transactional (message_type: "transactional") — transactional messages are not subject to frequency capping at all.

Please note: /createMessage is marked deprecated in the API reference. It remains operational, but new integrations should use the unified Messaging API v2, where capping_days becomes frequency_capping.days and capping_count becomes frequency_capping.count (see the migration guide).