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 hour, day, or week which a user will receive from a given OneSignal App.

Frequency Capping is a Paid Plan Feature.

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 > Messaging > Frequency Capping.

Frequency capping can be specified as a number of times per 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.

📘

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 capped 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 param.

• 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, sending true will apply the frequency capping to the notification. If the param is not included, the default behavior is to apply frequency capping if the setting is enabled for the app.
  Setting the param to false will override the frequency capping, meaning that the notification will be sent without considering frequency capping.

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.