Writing a journey
Steps, triggers, and how the assistant knows a step is finished.
A journey has a name (what the assistant calls it out loud), a trigger sentence, and its steps in order. You write it on the Journeys page; a coding agent connected over MCP can also draft one for you — a draft never runs until you publish it.
The trigger sentence#
The trigger is compared against what the visitor typed, so write a sentence, not a menu label: *"when the visitor wants to return or send back something they bought"*. A noun phrase like "Returns" matches almost nothing.
How a step ends#
Every step says how we know it finished. This is a closed list — there is no free-text condition, because a condition the engine cannot check is a condition that silently never fires.
| Ends when | Needs |
|---|---|
click_self | The step's own target was clicked. |
visible / hidden | A target element appears or disappears. |
filled | A target field has a value. |
url_change | The address changes to something you name. |
settled | A target stops changing. |
attempts | A number of tries. |
user_continue | The visitor presses Continue. Required for hold steps. |
Rule: A step that opens a page must end on something the page can show. Opening a page tears the script down and rebuilds it on the new page, so an event that was going to happen — a click — can never arrive: the step would open the page again on every load. The editor therefore offers only url_change, visible and filled for an "open a page" step, and the server refuses a plan that says otherwise. The engine also stops a step after two navigations, so a wrong plan can never leave your site reloading.
One more thing the engine does on your behalf: it waits for a step's target to appear (a few seconds, checking continuously) before deciding it is missing. A page that renders its form a moment after loading is normal, and it should not stop a journey.
Publishing#
What gets published is a specific version. Editing a published journey takes it back offline, so a plan that nobody approved can never be running on your site. Read the steps, then publish again.
Tip: Most of the work in a journey is naming the right elements on your page. A step's target has to match exactly one element — #country-select or select[aria-label="Passport"] are both fine if only one thing on the page answers to them, while a bare button is refused: a reference that could mean forty things is not a pointer. If you have a coding agent connected (see Coding agents), it can read your pages and draft the steps — you review and publish.