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

# Start, hide & trigger rules

> When a content auto-starts, when it hides, and the in-step triggers — all built from conditions and actions.

Version-level **start** and **hide** rules, plus per-step **triggers**, are how
content reacts. They reuse [conditions and actions](/api-reference-v2/conditions-and-actions).
Set them on the version with `PATCH …/versions/{id}` (`startRules`, `hideRules`;
triggers live on each step).

## Start rules

When the content auto-starts, and how often.

| Field                | Type                                                                | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `when`               | [Condition](/api-reference-v2/conditions-and-actions#conditions)\[] |          | Auto-start when these match. A **full replacement** when present; omit it to keep the stored conditions and patch only the settings (frequency / priority / …).                                                                                                                                                                                                                                                |
| `frequency`          | [Frequency](#frequency)                                             |          | How often it may show.                                                                                                                                                                                                                                                                                                                                                                                         |
| `priority`           | `highest` \| `high` \| `medium` \| `low` \| `lowest`                |          | Ordering when several could start at once.                                                                                                                                                                                                                                                                                                                                                                     |
| `waitSeconds`        | number                                                              |          | Delay in **seconds** (not ms) before the content becomes eligible after the conditions first match. The countdown survives the conditions un-matching mid-wait, but an elapsed wait guarantees nothing — the conditions are **re-checked at show time**, and the content starts at the next moment they match again (unlike a trigger wait, which fires its actions regardless). Capped at 300 by the runtime. |
| `startIfNotComplete` | boolean                                                             |          | Only start if the user hasn't completed it.                                                                                                                                                                                                                                                                                                                                                                    |

Send `startRules: null` to clear them.

### Frequency

| Field     | Type                                | Required | Description                                                                                                                                                                                                                                                                                                                                        |
| --------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`    | `once` \| `multiple` \| `unlimited` | yes      | `once` = show a single time; `multiple` = up to N per window; `unlimited` = every time the conditions match. Omitting `frequency` on a write seeds the builder default (`once`) — stored explicitly, visible on read-backs. A version stored with NO frequency (legacy data only) runs with NO limit and re-starts whenever its rules match again. |
| `every`   | `object{ times, duration, unit }`   |          | Re-show window — used by `multiple` (with `times`) and `unlimited`; ignored by `once`. `unit` ∈ `seconds`/`minutes`/`hours`/`days`. Manual and programmatic starts also count toward the `multiple` limit.                                                                                                                                         |
| `atLeast` | `object{ duration, unit }`          |          | Quiet period: only auto-start if no OTHER content of the SAME type has been shown within this window — and since only flows accept this knob, in practice: no other FLOW. A banner / checklist / launcher showing does NOT block it.                                                                                                               |

```json theme={null}
{
  "when": [{ "type": "current_url", "includes": ["/dashboard"] }],
  "frequency": { "mode": "once" },
  "priority": "medium"
}
```

## Hide rules

When to hide the content (even if started). Hiding **suspends** the session
rather than ending it — when the conditions stop matching, the same session
reappears at the same step.

| Field  | Type                                                                | Required | Description             |
| ------ | ------------------------------------------------------------------- | -------- | ----------------------- |
| `when` | [Condition](/api-reference-v2/conditions-and-actions#conditions)\[] | yes      | Hide while these match. |

Send `hideRules: null` to clear them.

## Step triggers

A step can carry **triggers** — run actions when conditions become true while the
step is showing (e.g. advance when an element appears). Triggers live on the
step's `triggers[]` (see [Content representation](/api-reference-v2/content-representation#steps-flow)).

| Field         | Type                                                                | Required | Description                                                                                                                                                                                     |
| ------------- | ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `when`        | [Condition](/api-reference-v2/conditions-and-actions#conditions)\[] |          | Fire when these match.                                                                                                                                                                          |
| `do`          | [Action](/api-reference-v2/conditions-and-actions#actions)\[]       | yes      | Actions to run.                                                                                                                                                                                 |
| `waitSeconds` | number                                                              |          | Delay in **seconds** (not ms) between `when` matching and `do` firing. The match is latched: the actions fire after the wait even if the conditions have since stopped matching. Capped at 300. |

```json theme={null}
{
  "when": [{ "type": "element", "target": { "selector": "#welcome-modal" }, "state": "present" }],
  "do": [{ "type": "goto_step", "step": "step-2" }]
}
```