> For the complete documentation index, see [llms.txt](https://documentation.pushly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.pushly.com/platform/segments.md).
# Segments
Segments allow you to group subscribers into separate audiences and target them with relevant notifications.
Each segment has a name and a set of conditions that define the audience to be targeted.
> **Note:** Building segments now uses visual grouping and instant-search value lists, but existing segments continue to target the exact same subscribers as before — nothing about how segments are evaluated has changed.
### Building a segment
Once you select **Create Segment**, you'll first choose a name for your segment. This should be something descriptive of the audience.
> **Tip:** If you're going to be creating several similar segments, consider using a nomenclature that makes them easy to categorize and search. For example, if you are creating many segments that define a user interest perhaps prefix the segments with "Interest: Movies" or "Sports: NFL".
Next, if you'd like your segment to override the default icon when it is targeted you may enable the "Override Default icon" option and upload an image. This is optional.
Next, choose the delivery channels this segment applies to (Web, Native Apple, Native Android), then move on to defining the conditions that make up your audience.
Conditions live in the **Conditions** section under the heading **All of the following are true** — every top-level condition you add here is joined by **AND**, and each one must match for a subscriber to be included.
* Choose **Add rule** to add a single condition.
* Choose **Add group** to add a nested group of conditions joined by **OR** — labeled **"Any of the following are true"** — where matching *any one* condition inside that group is enough.
Top-level rules and OR groups are joined by an "AND" divider between them.
Each condition is a row made up of a **Field**, an **Operator**, and a **Value**:
* The **Field** picker supports search — start typing (for example, "visit") and it filters and groups matching fields by category (such as **Behavior**) as you type.
* Depending on the field you choose, the row may show additional controls, such as a specific page tag, a count, or a time window.
* The **Value** field supports instant-search too — start typing and matching values appear in a dropdown to pick from.
* A new row opens with no field chosen; once you pick one, the operator and value controls adjust to match it.
* Click any existing row to reopen it for editing, with **Save**, **Cancel**, and **Delete** controls.
> **Tip:** Hovering a condition row reveals a duplicate control next to delete. Duplicating copies the condition directly below the original and opens it for editing, pre-filled — a fast way to build several similar rules.
Rows are validated as you build. An incomplete row is marked and blocks saving, with the reason shown directly on the row.
### Reading a segment at a glance
Collapsed conditions read as plain-language sentences rather than raw field/operator/value fragments, so a segment can be understood without opening every row. For example:
* `Keyword includes any of sports`
* `Page / Screen Tag Visit Frequency is at least 1 time in the last 7 Days where the page tag is sports`
### Attribute Definitions
We support several segmentation attributes out of the box and can add custom attributes using your own 1st and 3rd party data. Contact your account manager for more information on custom attributes.
| Category | Attribute | Definition |
| -------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Behavior | Subscription Age (Allow Age) | The number of days since the subscriber allowed permissions |
| Behavior | Subscription Date (Allow Date) | The date the subscriber allowed permissions |
| Behavior | Subscription URL (Allow URL) | The URL of the page on which the subscriber allowed permissions |
| Behavior | Subscription Prompt (Allow Prompt) | The prompt the subscriber saw when opting in |
| Behavior | Journey Status | Target subscribers who are/aren't part of a platform journey |
| Behavior | Keyword | Subscribers who clicked on a notification tagged with the chosen keyword |
| Behavior | Keyword Clicked Frequency | Set a time frame for when a subscriber clicked on a given keyword. For example, subscribers who clicked on the "politics" keyword once in the last 30 days |
| Behavior | Last on Site / App | The date of the last time the subscriber was on the website or app |
| Behavior | Notification Clicked | Choose a notification to create an audience of subscribers who clicked that notification |
| Behavior | Notification Click Count | Target subscribers based on how many times they have clicked in a given time frame |
| Behavior | Page / Screen URL Visit Frequency | Target subscribers based on which URLs or screens they visit and how often |
| Behavior | Page / Screen Tag Visit Frequency | Target subscribers based on the meta tags of the page or screen they visit, and how often |
| Device | Browser | The browser the subscriber was on when they allowed permissions |
| Device | Subscriber ID / Push ID | The device's Push ID copied via the Web / Browser push Instructions or Native App Push instructions |
| Device | External ID | The external ID is only available if you choose to pass this data to Pushly |
| Device | Type (Placement) | The type of device the subscriber was on when they allowed permissions (Desktop, Mobile, or Tablet) |
| Device | Operating System | The operating system the subscriber was on when they allowed permissions |
| Device | App Identifier (iOS Bundle / Android Package) | The app's bundle or package identifier on the subscriber's device |
| Device | App Version (Apple) | The version of the app installed on the subscriber's iOS device |
| Device | App Version (Android) | The version of the app installed on the subscriber's Android device |
| Device | Language | The device or browser language setting at the time of permission |
| Location | City | The city the subscriber was in the last time they visited your website |
| Location | Continent | The continent the subscriber was on the last time they visited your website |
| Location | Country | The country the subscriber was in the last time they visited your website |
| Location | Postal Code | The postal code the subscriber was in the last time they visited your website |
| Location | State / Province | The state/province/region the subscriber was in the last time they visited your website |
| Location | Map Area (Polygon) | Use the custom geo tool to select a geographic area you'd like to target. For a walkthrough of how to use the tool, click here |
| E-Commerce / Catalog | Purchase Count | Number of purchases made by the subscriber in the chosen time frame |
| E-Commerce / Catalog | Purchase Amount | Total purchase amount by the subscriber in the chosen time frame |
| E-Commerce / Catalog | Made / Completed Item Count | Count of items the subscriber added to cart or completed in the chosen time frame |
| E-Commerce / Catalog | Rated Item Count | Count of items the subscriber has rated in the chosen time frame |
| Custom | *(your domain's custom properties)* | Custom 1st/3rd-party properties configured for your account, listed by name |
| Custom | Advanced (any property) | Target on any property by name, including ones not otherwise listed |
> **Note:** The E-Commerce / Catalog definitions above should be confirmed with product before publishing — worded from field names, not from a written spec.
### When a segment can't be edited here
Some segments open **read-only**. The builder shows every condition and turns saving off so nothing is overwritten. There are two reasons this happens:
* **The segment includes a condition this builder doesn't support.** You can still read the whole segment; the unsupported condition is marked as locked. This is rare and usually means the segment was built with an older tool.
* **The segment applies to more than one domain.** Multi-domain segments are managed at the organization level — open it in multi-domain mode to edit it.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.pushly.com/platform/segments.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
