OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Time Operators

Use time-based triggers to send push notifications to users based on the time

Time-sensitive messages are crucial for a proper user experience and a successful app/site. OneSignal's Time Operators allows you to easily track "time elapsed greater than or less than" any past, present or future event. Common examples:

  • Abandoned Cart Messages - user's add items to their shopping cart. It is crucial to send them a reminder message if they fail to checkout after a certain amount of time.
  • Subscription Expiration Reminders - let users know ahead of time before their subscription ends and even create drip sequences if they lost track of time and forgot to re-register after subscription.
  • Important Events - If you have events going on in the app that users registered for, remind them days, hours and/or minutes in advance!
  • Milestones - Remind users about certain milestones they need to complete or send out

Time Operators work by adding a unix timestamp in seconds as a Data Tag value. For example: event : 1600968090 where event can be anything you want to track and is the tag "key" used to identify the event and 1600968090 is the past, present or future date of the event, expressed in Unix Timestamp Seconds Format.

Then through the User Tag segment filter or API Create notification tags filter you can target devices based on how long it has been since that date or time before that date will occur. Even setup Automated Messages for easy drip campaigns.


Paid Only Feature

"Time Elapsed" operators are only available on the paid plans.

Free plan can still use the default Time Related segment filters:

  • First Session: tracks the first time the user interacts with the app (with OneSignal active) or subscribes to the site.
  • Last Session: is the last time the device was on the app or site (if OneSignal is active).

"Time Elapsed" Operators

OneSignal supports the ability to create segments based on how much time has passed since a specific time stamp you specify with the Time Elapsed Greater Than and Time Elapsed Less Than operator.

This allows a much broader range of time-based actions than the first session and last session filters provided automatically as mentioned above.

Using a specific time stamp and the "Time Elapsed" operator can allow you to, for example, set a time that a user last took an action in your app, and then set up an automatic notification to send them a notification after a specified duration has passed.

Step 1: Set a Data Tag for a given player that represents a time (in UTC)

OneSignal.push(function() {
  let timestamp = Math.floor( / 1000);
  OneSignal.sendTag("event_key", timestamp).then(function(tagsSent) {
    // Callback called when tags have finished sending
long timestamp = Calendar.getInstance().getTime() / 1000;
OneSignal.sendTag("event_key", timestamp);

Step 2: Create a segment using the user tag filter, using the field from step 1 as the KEY, the "Time Elapsed Greater Than" operator, and the desired number of seconds as the VALUE.

Another example, you could send a notification to users who had not confirmed their email address within a week of you sending them a verification email.

By setting a data tag with the intro_email_time key and then using the "Time Elapsed Greater Than" and a value of 604800 (7 days X 24 hours X 60 minutes X 60 seconds).

You could send this as a one-off message, or if you automatically wanted to send an email to even new users who fall into that bucket, could use Automated Messages with this operator to automate on-boarding or engagement actions.


Abandoned Cart Example

If you have a checkout or payment system on your site, Time Operators are perfect for your use case. More details in our Abandoned Cart guide.

Target Device X days before Specific Time

Another helpful feature for Time Operators is the ability to send a notification X time before a certain date.

For example, if you want to send a notification 2 days before a specific date provided by the user.

When the user provides the date you want to track, you can convert that date to a unix timestamp and tag the user.

Then create a segment based on how long before the end date using "time elapsed greater than" and a negative time. 2 days for example would be - 172800 (60 seconds 60 minutes 24 hours * 2 days).


Paid Plan Feature

The "Time Elapsed" operator is included in all paid plans, but is not available on our Free tier.

Updated about a month ago

Time Operators

Use time-based triggers to send push notifications to users based on the time

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.