Push Frequency Capping

Apps and websites using OneSignal want to reach their users but don’t want to overwhelm them. High volumes of marketing emails or push notifications can cause users to unsubscribe or have a bad experience. Frequency capping allows you to specify the maximum number of messages per minute, hour, day, or week which a user will receive from a given OneSignal App.

Frequency Capping is available on selected Paid Plans.

Common Use Cases

Frequency Capping is most relevant for two primary use cases:

• Large organizations with multiple marketing campaigns running at a given time, potentially by different people.
• API-driven notifications triggered by a potentially frequent action (E.g. price changes in the stock market; news alerts that automatically fire)

Setup

To limit the number of messages sent to your users, you can set Frequency Capping from the app-level settings. Navigate to Settings > Push > Push Frequency Capping.

Frequency capping can be specified as a number of times per any number of MINUTE, HOUR, DAY, or WEEK. A day or a week is based on a rolling time window, that is, a day is the past 24 hours, a week is past 168 hrs. The maximum time limit is 1 week, or 168 hours.

📘

Capping applies to all messages sent to the user.

Messages that could not be delivered due to frequency capping setting are dropped. These messages will not be queued for later delivery.

If you set the cap to 2/day and send 2 API messages and 1 Journey message. The Journey will not be sent to the user unless you override the cap.

Override Frequency Capping

You can override the frequency capping for individual push and automated messages with the option under Delivery Schedule to “override frequency cap”.

🚧

Overriding Counts Towards Total

Messages that are sent with the ‘override frequency capping’ setting are still considered against the total capped count when sending other messages.

Reporting

Notification delivery reports (under Scheduled section) and exported CSV for delivery reports now include frequency cap details. You will see the following status:

• Uncapped: Frequency capping is not enabled for the app.
• Capped: Frequency capping is enabled for the app.
• Overridden: Frequency capping is enabled for the app, but was overridden for the notification.

API Access

Create Notification

Frequency capping needs to be enabled at an app-level from the dashboard in order to use this parameter.

• Parameter: enable_frequency_cap
• Type: boolean
• Platform: All, except Email and SMS. Frequency Capping is available for Push only.
• Description: When frequency capping is enabled for the app, it will default to true and will apply the frequency capping to all notifications. Setting this specifically to false will remove frequency capping from the message.

View Notification

Returned Fields
fcap_status:

• Uncapped: Frequency capping is not enabled for the app.
• Capped: Frequency capping is enabled for the app.
• Overridden: Frequency capping is enabled for the app, but was overridden for the notification.

Platform delivery stats response field details
If frequency capping is enabled on the app, frequency_capped will indicate the number of notifications that were not sent due to capping.