Segments

Segments update automatically as users interact with your app or site—no extra tracking required.

Segment counts only reflect opted-in Push, SMS, and Email subscriptions.When used in Journeys or In-App Messages, segments include users and opted-out subscriptions.To analyze unsubscribed subscriptions, use the Export CSV of Players API.

Segment types

The OneSignal platform supports two main categories of segments:

Subscription-based Segments

Subscription-based segments are built using filters on subscription attributes, such as device type, language, or app version.

User-based Segments

User-based segments are built using filters on user-level attributes rather than individual subscriptions. Currently, these segments support filters on message events and custom events. Examples include:

When a user last opened an email, SMS, or push notification sent via OneSignal.
Specific custom events tracked in your app or website.

A user-based segment includes all users who meet the criteria and automatically makes all of their subscriptions eligible to be targeted, enabling richer audience definitions that can reach any of the user’s devices.

Creating segments

Dashboard

Create and manage segments from Audience > Segments.

API

Create segments programmatically using the Create Segment API.

CSV Import

Bulk-import subscribers into a segment by uploading a CSV.

Create a segment in the dashboard

Go to Audience > Segments

Navigate to the Segments page in the dashboard.

Click New Segment

Opens the segment creation interface.

Add filters, name the segment, and click Create Segment

Configure your audience criteria and save.

Exclude segments

Exclude a segment to prevent its members from receiving a message or entering a Journey. Common use cases:

Avoid sending duplicate or conflicting messages
Respect user messaging preferences (e.g., “opted out of promo”)
Prioritize transactional messages over campaigns

You can exclude segments when:

Sending a message
Building a Journey
Using the Exclude Segment option in segment settings

Filters

Filters define which subscriptions belong to a segment. You can combine multiple filters using AND or OR logic.

Filter	Description
First session	Date/time of user creation.
Last session	Last time Subscription opened the app or site.
Session count	Number of times Subscription opened the app or visited the site.
Usage duration	Total seconds the Subscription had your app/site open.
Language	User’s preferred language (based on device/browser). See multi-language support.
App version	Pulled from Android `versionCode` or iOS `CFBundleShortVersionString`. Combine with Device type to filter by different app versions per platform. See Target outdated app versions.
Device type	iOS, Android, Web Push (browser), Email, etc.
User tag	Custom tags you set via the SDK or API. See Add Tags.
Location	Filter by radius from coordinates (lat/long). Requires at least 1 meter and up to 2 decimal places of precision. See location permission.
Country	Based on last IP geolocation (ISO 3166-2 code).
Test users	Users marked as Test Users.

| Message Event | Filter by message event (e.g., “clicked”, “delivered”, “failed”). See Message event filters. | | Custom Event | Filter by custom event (e.g., “purchase”, “user login”). See Custom event filters. |

Message event filters

Message event filters allow you to filter users based on their interaction with one of your messaging channels within a certain window.

First select the messaging channel you want to filter on, then specify the action to track and whether the user has or has not performed that action. You can specify a minimum, maximum, or exact number of times the user must have performed the action, as well as a time window ranging from the last 24 hours to the last 90 days. Use the between option to define a custom start and end range (in days ago). Trackable interactions by channel:

Channel	Trackable Interactions
Push	Sent, Received, Clicked, Failed
SMS	Sent, Delivered, Failed
Email	Sent, Delivered, Opened, Clicked, Bounced, Failed, Suppressed, Reported as spam
In-App	Received, Clicked

Segments created with message event filters are user-based.They cannot be combined with subscription-based segments for inclusion or exclusion when sending messages outside of Journeys.Within Journeys, which is user-based, you can combine event-based and subscription-based segments for more flexible targeting.

Custom event filters

Custom event filters let you target users based on meaningful actions they have taken in your app, website, or external systems.

Custom event filters are currently in Early Access.To request access, contact support@onesignal.com with your company name, OneSignal Organization ID, and App ID(s).

Using custom event filters

Start by selecting the event type you want to filter on. Then specify:

The action you want to track.
Whether the user has or has not performed that action.

You can also set conditions such as:

Minimum, maximum, or exact number of times the action must be performed.
A time window during which the action must (or must not) occur — choose a preset range or define a custom window using the between option (start and end in days ago).

Event properties

After selecting an event type, you can optionally filter on event properties. You can include filters on multiple properties:

Choose all — applies an AND condition across properties.
Choose at least one — applies an OR condition.

Custom events are represented as JSON Objects. See the full structure here.Nested event properties can be referenced using dot notation.ExampleGiven the following custom event structure:

{
  "signup": {
    "method": "google",
    "experiment_group": "control_group",
    "referral_code": "SAVE15",
    "location": {
      "timezone": "Europe/Paris",
      "country": "CA"
    },
    "metadata": {
      "labels": ["red", "green", "blue"]
    }
  },
  "user_id": "user_804f7e88"
}

You can filter by:

signup.referral_code → to target users with referral code SAVE15.
signup.location.country → to target users in Canada.
metadata.labels.0 → to target users with label red.

Segments created with custom event filters are in Early Access and are user-based. A custom event segment can only contain custom event filters, and cannot be combined with other segments for inclusion or exclusion when sending messages.

Segment logic: AND vs OR

Use AND to combine filters that all must match. Use OR to match any of multiple conditions.

AND example
OR example

Create a segment of users who:

Have not returned in more than 7 days
Will be removed after 11 days

Managing segments

View users

Click Options > View Users to see which subscriptions are in the segment.

Edit

Click the segment name or Options > Edit to change filters.

Pause / Resume

If you’re near your segment limit (based on your plan), you can pause segments. Targeting a paused segment will fail.

Set as default

Set a default segment to be auto-selected when sending a new message. This helps reduce targeting mistakes and save time.

Duplicate

Copy a segment’s filters to create a new one.

Deleting segments

Deleting a segment cannot be undone and does not delete the users inside it.

Dashboard
API

Go to Audience > Segments
Click the three-dot menu next to a segment
Select Delete

Use the Delete Segment API. This only removes the segment definition.To delete users in the segment, use the Delete Users API.

{
  "name": "Segment 2",
  "filters": [
    { "field": "session_count", "relation": ">", "value": "1" },
    { "operator": "AND" },
    { "field": "tag", "relation": "!=", "key": "tag_key", "value": "1" },
    { "operator": "OR" },
    { "field": "last_session", "relation": "<", "hours_ago": "30" }
  ]
}

FAQ

How do I add myself to a segment?

Find your Subscriptions using your External ID.
Either:

Set yourself as a Test user
Add a custom Tag

Create a segment using the Test Users filter or the tag.

Do segment counts include opted-out users?

Visible counts only include opted-in subscriptions.
Segments used in Journeys and in-app messages include both subscribed and unsubscribed subscriptions.
To see unsubscribed subscriptions, use the Export CSV of Players API.

Are segment counts always accurate?

Segments larger than 80,000 total users may show an estimated size rather than a precise count for performance. For the most accurate numbers, see the message report stats after sending the message.

What types of in-app purchases are tracked?

Tracked: Consumable purchases made while the OneSignal SDK is active.
Not tracked: Subscription purchases.
To import historical purchase data, use the Update User API with the purchases parameter.

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

Segment types

Subscription-based Segments

User-based Segments

Creating segments

Dashboard

API

CSV Import

Create a segment in the dashboard

Exclude segments

Filters

Message event filters

Custom event filters

Segment logic: AND vs OR

Managing segments

Deleting segments

FAQ

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​Segment types

​Subscription-based Segments

​User-based Segments

​Creating segments

Dashboard

API

CSV Import

​Create a segment in the dashboard

​Exclude segments

​Filters

​Message event filters

​Custom event filters

​Segment logic: AND vs OR

​Managing segments

​Deleting segments

​FAQ

Segment types

Subscription-based Segments

User-based Segments

Creating segments

Create a segment in the dashboard

Exclude segments

Filters

Message event filters

Custom event filters

Segment logic: AND vs OR

Managing segments

Deleting segments

FAQ