> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Audiences

> Build targeted segments with the audience builder

This guide walks you through creating an audience from scratch using the Trackly SMS audience builder.

## Accessing the Audience Builder

1. Navigate to **Audiences** in the sidebar
2. Click **New Audience** in the top right
3. The audience builder opens

## Basic Structure

Every audience has:

* **Name**: A descriptive name (e.g., "Active Clickers - CA")
* **Lists**: Which sending lists to query
* **Conditions**: Filter rules that define who's included

## Step 1: Name Your Audience

Choose a descriptive name that explains who's in this audience:

<Tabs>
  <Tab title="Good Names">
    * "High-Value Clickers - Last 30 Days"
    * "California Subscribers - No Clicks"
    * "Black Friday 2024 Signups"
    * "Revenue > \$100 - Re-engagement"
  </Tab>

  <Tab title="Avoid">
    * "Audience 1"
    * "Test"
    * "New Audience"
    * "asdf"
  </Tab>
</Tabs>

## Step 2: Select Lists

Choose which sending lists to include:

* **Single list**: Only contacts on that list
* **Multiple lists**: Contacts on ANY of the selected lists

<Note>
  Selecting multiple lists creates a UNION. A contact matching your conditions on List A OR List B will be included.
</Note>

## Step 3: Add Conditions

Click **Add Condition** to add your first filter.

### Condition Structure

Each condition has three parts:

| Part         | Description       | Example           |
| ------------ | ----------------- | ----------------- |
| **Field**    | What to filter on | `last_clicked_at` |
| **Operator** | How to compare    | `within`          |
| **Value**    | The threshold     | `7 days`          |

### Available Fields

<AccordionGroup>
  <Accordion title="Time-Based Fields">
    | Field             | Description                       |
    | ----------------- | --------------------------------- |
    | `last_sent_at`    | When they last received a message |
    | `last_clicked_at` | When they last clicked a link     |
    | `signup_date`     | When they joined the list         |
  </Accordion>

  <Accordion title="Count-Based Fields">
    | Field         | Description             |
    | ------------- | ----------------------- |
    | `send_count`  | Total messages received |
    | `click_count` | Total links clicked     |

    `conversion_count` is not exposed as a direct audience condition. Conversion-based targeting is available through the revenue condition type.
  </Accordion>

  <Accordion title="Revenue Fields">
    | Field              | Description                         |
    | ------------------ | ----------------------------------- |
    | `has_revenue`      | Has made any purchase (boolean)     |
    | `revenue_total`    | Lifetime revenue                    |
    | `avg_revenue`      | Average order value                 |
    | `conversion_count` | Total number of conversions         |
    | `last_revenue_at`  | Timestamp of most recent conversion |
  </Accordion>

  <Accordion title="DNC (Do Not Call)">
    | Field    | Description                                                                                        |
    | -------- | -------------------------------------------------------------------------------------------------- |
    | `on_dnc` | Boolean — whether the contact is on the Do Not Call list. Use `eq` operator with `true` or `false` |
  </Accordion>

  <Accordion title="Carrier & Timezone">
    | Field      | Description                                                                                      |
    | ---------- | ------------------------------------------------------------------------------------------------ |
    | `carrier`  | Mobile carrier name (e.g., "T-Mobile", "Verizon"). Operators: `eq`, `in`, `exists`, `not_exists` |
    | `timezone` | IANA timezone (e.g., "America/New\_York"). Operators: `eq`, `in`                                 |

    Carrier and timezone conditions require a cross-collection lookup and are slower than ListContact-only conditions.
  </Accordion>

  <Accordion title="Signup History">
    | Field           | Description                                                                                    |
    | --------------- | ---------------------------------------------------------------------------------------------- |
    | `signup_method` | How the contact was added (`api`, `web_form`, `import`). Operators: `eq`, `ne`, `in`, `not_in` |

    Can be combined with optional time-based filtering on signup date.
  </Accordion>

  <Accordion title="Custom Fields">
    Any field you've defined on contacts. These query `custom_fields.{key}` on ListContact:

    * `state` (queries `custom_fields.state`)
    * `city` (queries `custom_fields.city`)
    * `plan_type` (queries `custom_fields.plan_type`)
    * `signup_source` (queries `custom_fields.signup_source`)
    * etc.
  </Accordion>
</AccordionGroup>

### Available Operators

| Operator     | Use With     | Example                                     |
| ------------ | ------------ | ------------------------------------------- |
| `eq`         | Text, number | State eq "CA"                               |
| `ne`         | Text, number | Status ne "churned"                         |
| `in`         | Text, number | State in \["CA", "TX", "FL"] (is one of)    |
| `not_in`     | Text, number | State not\_in \["AK", "HI"] (is not one of) |
| `contains`   | Text         | Email contains "@gmail"                     |
| `gt`         | Number       | Revenue gt 100                              |
| `lt`         | Number       | Send count lt 5                             |
| `gte`        | Number       | Click count gte 3                           |
| `lte`        | Number       | Send count lte 10                           |
| `within`     | Date         | Clicked within 7 days                       |
| `not_within` | Date         | Not clicked within 30 days                  |
| `before`     | Date         | Signed up before Jan 1                      |
| `exists`     | Any          | Has phone number                            |
| `not_exists` | Any          | Missing email                               |

## Step 4: Combine with Logic

### AND Logic (Default)

All conditions must match:

```
Condition 1: last_clicked_at within 7 days
AND
Condition 2: custom_fields.state eq "California"
```

Both must be true for a contact to be included.

### OR Logic

Click the condition group header to switch to OR:

```
Condition 1: custom_fields.state eq "California"
OR
Condition 2: custom_fields.state eq "Texas"
```

Either condition can be true.

### Nested Groups

Click **Add Group** to create a nested set of conditions:

```
Group 1 (AND):
  - last_clicked_at within 7 days
  - revenue_total gt 50

OR

Group 2 (AND):
  - signup_date within 30 days
  - click_count gt 0
```

This matches:

* Recent clickers with revenue, OR
* New signups who have clicked

## Step 5: Preview and Save

### Preview

Click **Preview** to see:

* Estimated audience size
* Sample contacts that match
* Any issues with your conditions

### Save

Click **Create Audience** to save.

The audience appears in your list and can now be used in campaigns.

## Example: High-Value Recent Clickers

Let's build an audience of valuable contacts who are engaged:

<Steps>
  <Step title="Name it">
    "High-Value Clickers - 30 Days"
  </Step>

  <Step title="Select lists">
    Choose your main marketing list
  </Step>

  <Step title="Add time condition">
    Field: `last_clicked_at`
    Operator: `within`
    Value: `30 days`
  </Step>

  <Step title="Add revenue condition">
    Field: `revenue_total`
    Operator: `gt`
    Value: `50`
  </Step>

  <Step title="Preview and save">
    Check the preview, then save
  </Step>
</Steps>

## Editing Audiences

To edit an existing audience:

1. Go to **Audiences**
2. Click the audience name
3. Make your changes
4. Click **Save**

<Warning>
  Editing an audience affects all campaigns using it. The new definition applies to future sends.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Segmentation Logic" icon="diagram-project" href="/guides/audiences/segmentation-logic">
    Advanced AND/OR patterns
  </Card>

  <Card title="Use in Campaigns" icon="paper-plane" href="/guides/campaigns/overview">
    Target your audience
  </Card>
</CardGroup>