> ## 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. # Conditions & actions > The reusable predicate and behavior primitives — used by start/hide rules, step triggers, and button/question actions. **Conditions** decide *whether* something applies; **actions** decide *what happens*. They're the same shapes everywhere they appear: version [start/hide rules](/api-reference-v2/rules), step triggers, and button / question `actions`. ## Conditions A condition list is **AND** by default. Use a `group` to express **OR** (or to nest): a group's `match` is how its children combine (`all` = AND, `any` = OR). A group must hold **at least one** condition — an empty group is not "no filter", it is a node that never matches, so next to an AND it makes the whole rule unmatchable. Writing one is rejected. A version saved with an empty group in the builder still reads back with it and draws a validate warning; writing that list back is refused until the group is filled or dropped. ```json theme={null} [ { "type": "segment", "segment": "cm9f6vwed0002iejc4vg2zu3t", "in": true }, { "type": "group", "match": "any", "conditions": [ { "type": "current_url", "includes": ["/pricing"] }, { "type": "current_url", "includes": ["/billing"] } ]} ] ``` #### `group` | Field | Type | Required | Description | | ------------ | ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"group"` | yes | | | `match` | `all` \| `any` | yes | | | `conditions` | [Condition](/api-reference-v2/conditions-and-actions#conditions)\[] | yes | The grouped conditions — at least one. An EMPTY group is not "no filter": it never matches, so next to an AND it makes the whole rule unmatchable, and writing one is rejected. A version saved with an empty group in the BUILDER still reads back with it (validate warns); writing that list back is refused until the group is filled or dropped. | #### `attribute` | Field | Type | Required | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"attribute"` | yes | | | `scope` | `user` \| `company` \| `companyMembership` | yes | Which entity owns the attribute — `user` (the end user), `company`, or `companyMembership`. Same value as the attribute definition's `scope` (see the attribute definitions list); required to disambiguate a codeName that exists in more than one scope. | | `attribute` | string | yes | | | `op` | `is` \| `not` \| `contains` \| `not_contains` \| `starts_with` \| `ends_with` \| `any` \| `empty` \| `lt` \| `lte` \| `gt` \| `gte` \| `between` \| `true` \| `false` \| `includes_any` \| `includes_all` \| `not_includes_any` \| `not_includes_all` \| `less_than` \| `exactly` \| `more_than` \| `before` \| `on` \| `after` | yes | Operator — the allowed set depends on the attribute dataType. String: is \| not \| contains \| not\_contains \| starts\_with \| ends\_with \| any \| empty. Number: is \| not \| lt \| lte \| gt \| gte \| between \| any \| empty. Boolean: true \| false \| any \| empty. List: includes\_any \| includes\_all \| not\_includes\_any \| not\_includes\_all \| any \| empty. DateTime: less\_than \| exactly \| more\_than (relative — `value` is a number of days) \| before \| on \| after (`value` is an absolute date) \| any \| empty. The relative ops are ONE-SIDED bounds around (now − N days): `less_than N` = the date is AFTER now−N — so it also matches every FUTURE date, and on a future-dated attribute (a trial end, a renewal date) it is NOT "within the last N days"; `more_than N` = the date is BEFORE now−N. **"Signed up in the last N days" therefore needs BOTH bounds** — `less_than N` AND `more_than 0` in one `all` group; `less_than N` alone silently includes anyone whose date is in the future (a mis-mapped trial-end column, a clock/timezone slip), and those are exactly the users a new-user audience must not contain (observed in testing). Negative N shifts the bound into the future: the rolling "within the NEXT 7 days" window is `less_than` value "0" AND `more_than` value "-7" (two conditions, both required). The relative ops are DAY-granularity only — no unit field; for hour/minute windows use an `event` condition with a `within` (which has a `unit`). | | `value` | string | | The comparison value (string / number-as-string / date). Omit for any/empty/true/false. | | `value2` | string | | Upper bound for the `between` operator (`value` is the lower bound). | | `values` | string\[] | | Values for the List operators (includes\_any / includes\_all / …). | The same shape with `type: "event_attribute"` (and no `scope`) filters on an **event's own** attributes — valid only inside an `event` condition's `where`. #### `segment` | Field | Type | Required | Description | | --------- | ----------- | -------- | ----------- | | `type` | `"segment"` | yes | | | `segment` | string | yes | | | `in` | boolean | yes | | #### `current_url` | Field | Type | Required | Description | | ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `"current_url"` | yes | | | `includes` | string\[] | yes | URL patterns (anchored whole-url match, NOT substring/regex). `*` = wildcard within one url part; `:name` = one path segment. A bare `*` (i.e. `["*"]`) matches EVERY page on every host incl. deep paths — the canonical always-on / whole-site pattern (use it when content should be available everywhere). Scope it down instead with: `*/` (homepage only — path exactly `/`), `*/pricing` (one page), `*/app/*` (a section + below), `host.com/*` (any page on a specific host). Multiple patterns are OR-matched: the URL matches this list if it matches ANY one pattern (so "/tasks OR /dashboard" is one condition with both patterns here — no group needed). | | `excludes` | string\[] | | URL patterns to exclude (same syntax as includes); excludes win over includes. | #### `element` | Field | Type | Required | Description | | -------- | ---------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"element"` | yes | | | `target` | Target | | | | `state` | `present` \| `hidden` \| `disabled` \| `enabled` \| `clicked` \| `unclicked` | yes | `present` means NOT CLIPPED AWAY: the element is in the DOM and its box lies inside the viewport / its scroll ancestors — scrolled off-screen or `display:none` never satisfies it (and `hidden` is its negation). It is NOT "the user can see something there": an EMPTY, zero-height placeholder node satisfies `present` (observed in testing: a checklist task keyed on an initially-empty `

` status line ticked itself the moment the checklist appeared, before the shopper did anything). So do not use element presence as a proxy for "the app has said something": most apps keep the container mounted and only fill in its text. Match the TEXT instead (`target.text` + `present`, or the negation trick: the old text `hidden`). Appearances shorter than about a second can be missed entirely. `disabled`/`enabled` read the element disabled state at evaluation time. **`clicked` means "clicked since page load AND the element is STILL in the DOM right now"** — both halves, re-checked every evaluation. The click memory latches (the listener attaches the FIRST time the condition is evaluated, so earlier clicks are invisible, and the memory survives a re-render), but the element lookup is redone each poll. Two consequences, one of them silent: (1) **an element that UNMOUNTS on click can NEVER satisfy it** — the click lands, the element vanishes, the lookup fails from then on and the condition stays false forever with no error (observed in testing: a tracker on a button that clears its own toolbar counted ZERO real clicks); (2) an element that unmounts and REMOUNTS satisfies it again, so a tracker gated on it fires once per remount — not once per page load. Unlike `present`, this lookup does NOT require viewport visibility: scrolling the target off-screen keeps `clicked` true. `unclicked` negates the same pair, so it is also false while the element is absent. To count a COMPLETED action, condition on what the app shows afterwards (a success toast, a state change) rather than `clicked` on the button that starts it. | #### `content_state` | Field | Type | Required | Description | | --------- | ---------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"content_state"` | yes | | | `content` | string | yes | contentId of the FLOW or CHECKLIST whose per-user state to check (an id from the content list). Only flows and checklists record this state — referencing a banner / launcher / resource-center / tracker is rejected at write. | | `state` | `seen` \| `unseen` \| `completed` \| `uncompleted` \| `active` \| `inactive` | yes | The referenced flow/checklist's state for THIS user. seen = started at least once (for a flow, TRUE from the moment it opens; for a checklist, TRUE only once the user EXPANDS the panel — a `initialDisplay: "button"` checklist whose launcher is never clicked stays unseen forever); unseen = never started; active = currently open/running; inactive = NOT currently running (covers both never-started and ran-then-closed); completed = reached a goal/completion step; uncompleted = not completed. To gate piece B until flow A has run AND closed (the usual "show next thing after the welcome flow" sequencing), use `seen` AND `inactive` together — `seen` alone fires while A is still open (B piles on top), and `completed` alone strands users who skip/dismiss A. | #### `event` | Field | Type | Required | Description | | -------- | -------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `"event"` | yes | | | `event` | string | yes | | | `count` | `object{ op, n, n2 }` | | How many times the event must have occurred. Omit it for the common case "the event has happened" (treated as at\_least 1). Set `op`/`n` for a threshold (`between` needs `n` and `n2`). `at_least`/`between` require n ≥ 1; use `at_most`/`exactly` with 0 for "never happened". | | `within` | `object{ op, value, value2, unit }` | | Optional time window for the event count. Omit it (or use `any_time`) to count over all time — "the event has ever happened". Any other `op` (`in_the_last` / `more_than` / `between`) requires BOTH `value` and `unit`, and `between` also `value2` — rejected at write otherwise. | | `scope` | `current_user` \| `current_user_in_company` \| `any_user_in_company` | | Whose event activity to count (default `current_user`). `current_user` = only this user's own events. `current_user_in_company` = this user's events, but counted within their currently-associated company context (needs the user associated to a company via `group()` / the company-membership API). `any_user_in_company` = events by ANY user in this user's company — account-level activity (e.g. "anyone on the account has done X"). The two company scopes require the user to be in a company or they never match. | | `where` | [Condition](/api-reference-v2/conditions-and-actions#conditions)\[] | | | #### `text_input` | Field | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- | | `type` | `"text_input"` | yes | | | `target` | Target | | | | `op` | `is` \| `not` \| `contains` \| `not_contains` \| `starts_with` \| `ends_with` \| `match` \| `unmatch` \| `any` \| `empty` | yes | | | `value` | string | | | #### `text_filled` | Field | Type | Required | Description | | -------- | --------------- | -------- | ----------- | | `type` | `"text_filled"` | yes | | | `target` | Target | | | #### `time_window` | Field | Type | Required | Description | | ------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `"time_window"` | yes | | | `start` | string | yes | Window start (ISO datetime). REQUIRED — the runtime never matches a window without a start, so an end-only window is rejected at write. For "until X" semantics, set start to any past instant and end to X. | | `end` | string | | Window end (ISO datetime). Omit for an open-ended "from start onwards" window. | #### `task_clicked` Parameterless (`{ "type": "task_clicked" }`). Valid only in a checklist item's `completeWhen` — the item completes when clicked. #### `unsupported` Read-back only: a stored condition the representation cannot express is returned as `{ "type": "unsupported", "note": "…" }` — usually a DEAD condition the runtime never matches (deleted attribute/event, end-only time window); the `note` says which. It cannot be written back: **echoing it is rejected** (E1017) — the placeholder carries no data to preserve. Either remove it from the list you write, an explicit choice that DELETES the stored condition (mind: a never-matching node inside an AND list pins the whole rule to "never fires", so deleting it can bring the remaining conditions to life), or repair the original condition in the Usertour builder first. The same contract applies to segment conditions. ## Actions #### `goto_step` | Field | Type | Required | Description | | ------ | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `type` | `"goto_step"` | yes | | | `step` | string | yes | Target step: a step `key` declared elsewhere in the same write, or an existing step cvid. Resolved server-side to the cvid. | #### `start_content` | Field | Type | Required | Description | | --------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"start_content"` | yes | | | `content` | string | yes | contentId of the flow or checklist to launch (an id from the content list) — a raw content id, NOT a step key (unlike goto\_step). Must reference a flow or checklist (a banner / launcher / resource-center / tracker is rejected at write). The target must be PUBLISHED to actually start at runtime; an unknown/dangling id is rejected at validate. | | `step` | string | | Optional cvid of a step within the launched flow to start at. | #### `navigate` | Field | Type | Required | Description | | -------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `"navigate"` | yes | | | `url` | string | yes | Absolute URL, or an app-relative path ("/docs/x") resolved against the origin the user is on — relative paths are the normal choice for in-app navigation. | | `newTab` | boolean | | Open the URL in a new browser tab instead of navigating the current one. | #### `dismiss` | Field | Type | Required | Description | | ------ | ----------- | -------- | ----------- | | `type` | `"dismiss"` | yes | | `run_javascript` is **echo-only**: builder-authored script actions appear on reads, and echoing one back **unchanged** preserves it when you rewrite the surrounding list (action lists are full replacements — leaving it out deletes it). Authoring a new or edited script is rejected (no API/agent-injected JavaScript). ```json theme={null} { "type": "button", "text": "See pricing", "actions": [{ "type": "navigate", "url": "/pricing", "newTab": true }] } ``` ## Target An element reference (used by `element` / `text_input` / `text_filled` conditions, tooltip steps, and banner container). | Field | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `selector` | string | yes | A stable CSS selector for the element in your app. | | `text` | string | | Visible text the targeted element must **equal** (exact match, after trim) — refines the element chosen by `selector`/`nth`; it does not search among multiple matches. | | `nth` | number | | 0-based index of the match when the selector isn't unique, in document order. Range 0–4 (only the first 5 matches are addressable). | ```json theme={null} { "selector": "[data-tour='create']" } ``` ```json theme={null} { "selector": "button.cta", "text": "Save", "nth": 0 } ```