Automate time-based messages using Time Elapsed operators with Tags that store Unix timestamps in seconds.
Overview
Time Operators let you send messages relative to a specific moment in time—such as after an action happens or before an upcoming date.You store that moment as a Unix timestamp (in seconds) on the user using a Tag. OneSignal then compares the current time to that timestamp and lets you target users based on how much time has passed (or how much time remains).This makes it easy to automate messages like reminders, follow-ups, and deadlines without scheduling messages manually.Common use cases:
Abandoned cart: Remind users who haven’t checked out after a certain time
Event reminders: Message users before a scheduled appointment or renewal date
Milestones: Follow up when users haven’t completed an action by a deadline
Birthdays: Send messages on (or around) a user’s birthday
Time Operators are only available on paid plans. Free plans can still use
default time-based segment filters like First active and Last active.
When should I use this?
Use Time Operators when you want to:
Send messages relative to an event, not at a fixed calendar time
Create moving time windows (for example, “24–48 hours after”)
Reuse the same logic for many users with different dates
Continuously evaluate eligibility as time passes
If you need to trigger messaging immediately when an event occurs, consider using Custom Events instead.
Tags vs Custom Events
You can solve many “reminder” use cases with either Tags or Custom Events. The best option depends on what you need to store and how you want to trigger automation.
Use Tags when you want to store the latest known timestamp on the user (for example, cart_updated_at or subscription_expires_at) and segment off that value over time.
Use Custom Events when you want to record each event occurrence (with properties) and trigger Journeys based on real-time behavior.
In practice, many implementations can use both: Custom Events for real-time tracking and Tags for user state you want to segment on later.
Tags and Custom Events are both ways to add data to your users. However, there are some key differences:
Feature
Tags
Custom Events
Data usage
Segmentation and personalization
Segmentation, Journey triggers, Wait Until steps, and personalization within Journeys
Segmentation, Journeys, and Journey-message-template personalization
The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.In practice, you will likely use both:
Tags for user properties that are static and don’t change often
Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows
Quick reference
Convert the event date into a Unix timestamp in seconds.
Set a Tag where the key is the event name and the value is the timestamp as a string (e.g., 'event_date': '1739145600').
Create a segment using the Time Elapsed Greater Than operator:
After a past date using Time Elapsed Greater Than operator with a positive value
Before a future date using Time Elapsed Greater Than operator with a negative value
A common mistake is setting timestamps in milliseconds (13 digits) instead
of seconds (10 digits). Time Operators require seconds.
Send messages after a past event
Use this pattern when you want to message users after a certain amount of time has passed since something happened.Example: Abandoned cart reminder 24 hours after the user updated their cart
1
Store the timestamp when the event happens
When the user updates their cart, save the current time as a Unix timestamp (in seconds):
Set re-entry to 52 weeks so users can re-enter next year
Update the birthday tag to next year’s date after sending (in your backend or Journey)
Calculate birthday timestamps using the user’s local timezone when possible.
Using server time only may cause messages to send earlier or later than
expected.
If you want messages to stay accurate year-over-year, update the user’s
birthday tag to the next upcoming birthday after you send the message (for
example, in your backend or in a Journey step). Keep in mind, if you do this,
it may be easier to use Custom Events instead.
Birthday messages will be sent to users around their birthday tag date.
FAQ
How does the math work? (technical details)
Time Operators exist to let you create relative, moving windows instead of fixed dates.OneSignal calculates elapsed time using this formula:
time_elapsed = current_time - tag_timestamp
Past timestamps → positive values
Future timestamps → negative values
Operators:
Time Elapsed Greater Than X: matches when elapsed > X
Time Elapsed Less Than X: matches when elapsed < X
Why future timestamps match immediately with Less Than:Any negative number is less than any positive number. So time_elapsed_lt 2 days (172,800 seconds) will match a timestamp 30 days in the future because:
-2,592,000 < 172,800 → true (matches)
Because future timestamps always produce negative elapsed time, you must use negative values to define when users should enter and exit segments before an upcoming event. Positive values cannot represent time before a future date.
How can I test?
Find your user via the External ID, Subscription ID, Email or Phone number. See Find and set Test Users for details on finding your user.
Get a timestamp in seconds of the current date and a future date (5 minutes from now).
Set two tags with the keys ‘current_time’ and ‘future_time’ and the values as the timestamps in seconds.
Create a current_time segment with the following filters:
User Tag: current_timeTime Elapsed Greater Than: 2 minutes
AND User Tag: current_timeTime Elapsed Less Than: 5 minutes
Create a future_time segment with the following filters:
User Tag: future_timeTime Elapsed Greater Than: -5 minutes
AND User Tag: future_timeTime Elapsed Less Than: -2 minutes
You should see your user:
Enter the current_time segment 2 minutes after the current time date and exit the segment 5 minutes after the current time date.
Enter the future_time segment 5 minutes before the future time date and exit the segment 2 minutes before the future time date.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.