Journeys (Phase 11)
A journey is an automated flow that enrolls a user through a trigger and moves them through wait, condition, branching and send steps (the equivalent of the legacy provider's Journeys). In the API, the resource name is journeys, the field name is journey_id, and the event…
A journey is an automated flow that enrolls a user through a trigger and moves them through wait, condition, branching and send steps (the equivalent of the legacy provider's Journeys). In the API, the resource name remains journeys, the field name journey_id, and the event name journey.*. Design decisions: docs/adr/0018-journey-motoru.md. Schema and validation: packages/shared/src/journeys.ts.
Lifecycle
| Status | Meaning |
|---|---|
draft | Never published; can be deleted. |
active | Live; new entries are accepted and runs progress. |
paused | No new entries; waiting runs are held; continues with resume. |
archived | Permanently closed; open runs are exited with reason journey_archived. |
Edits are always made on the draft version (PUT …/draft, PATCH …/nodes/:nodeId). publish publishes the draft as a new version. Active runs stay on the version they entered (version pinning); new entries use the latest version. Structural and semantic validation runs before publishing; if there are problems, 400 and details.issues are returned.
Graph format
It is compatible with React Flow:
{
"nodes": [{ "id": "t", "type": "trigger", "position": { "x": 0, "y": 0 }, "data": { "trigger": { "kind": "event", "event_name": "signup" } } }],
"edges": [{ "id": "e1", "source": "t", "target": "w", "sourceHandle": "next" }]
}Rules:
- There is exactly one
triggernode, and cycles are not allowed. - Every node must be reachable from the trigger.
- Each output handle connects to at most one edge; an unconnected handle means the run is
completedat that point. - Limits are in
JOURNEY_LIMITS: at most 100 nodes, 200 edges and 5 branches; waits range from 60 s to 365 days.
Node types
| Type | Data | Handles |
|---|---|---|
trigger | trigger.kind: event (+property_filters), segment_enter, api, schedule (segment_id, 5-field cron, timezone) | next |
wait | wait.mode: duration (seconds), until_time (HH:MM, user/app time zone), until_date (at) | next |
wait_until | conditions[]: event, segment_enter, message (node_id + event) and timeout_seconds | cond_0…cond_n, timeout |
time_window | windows[] (days 0=Sunday…6, start, end) and time zone; if outside the window, waits until the next window | next |
condition | rule: segment, filters (segment AST), message (event of an upstream send), event (within_days) | yes, no |
ai_decision | agent_id, arms[]. The decision agent picks the best option for the user; it does not send a message (ADR-0074) | options and none |
channel_decision | channels[] (2–5; push, email, whatsapp, rcs, sms). Picks the user's best channel; it does not send a message (ADR-0069) | selected channels and none |
split | branches[] (id, percent; total 100). Assignment is deterministic via run_id (FNV-1a) | branch IDs |
send_push / send_email / send_sms | template_id or inline content | next |
send_in_app | in_app_message_id, expires_seconds | next |
webhook | url, headers, Liquid body (POST only) | next |
update_tags | tags (a null value deletes the tag) | next |
exit | — | — |
Message events: sent, delivered, opened, clicked, failed, bounced, complained, unsubscribed.
Push → SMS fallback example: send_push → wait_until [message (push node, delivered), timeout 1 hour] → timeout handle → send_sms.
Send steps
- Each send creates a
messagesrecord with the fieldssource = journeyandjourney_run_id. The send goes through the normal delivery pipeline, and campaign analytics also work off this record. - If the user has no active subscription on that channel, the step becomes
skippedand the run continues. - Quiet hours and frequency caps apply; you can exempt a journey with
settings.quiet_hours_exemptandfrequency_cap_exempt. send_in_appgives the user a time-limited display grant (in_app_journey_grants). In-app messages withjourney_only: trueare shown only to users who have this grant.- The body of a
webhooknode is written in Liquid;user,journey,runandcontext(the entry context) are in scope.- If no body is given, a default JSON body is sent:
{type: "journey.webhook", journey_id, node_id, run_id, user, context}. - Every request carries the
idempotency-key: <run_id>:<node_id>header. - SSRF protection is applied.
- A failed request does not stop the run; the result is written to the step statistics.
- If no body is given, a default JSON body is sent:
Settings (settings)
| Field | Description |
|---|---|
re_entry.mode | never (default), after_exit, after_days (+days) |
only_new_users | For segment triggers, only users who enter the segment after publishing |
exit_rules[] | event, segment_enter, segment_exit, unsubscribed, became_active |
exit_tags | Tags to write on exit (rule, goal, exit node) |
goals[], exit_on_goal | Goal event/segment; conversion rate statistics |
schedule.start_at / end_at | The window in which new entries are accepted |
quiet_hours_exempt, frequency_cap_exempt | Exemption from send restrictions |
Execution and reliability
- The database is the source of truth. Each step is claimed with an optimistic lock on
step_seq; running the same job twice has no effect. - Waiting runs are tied to a delayed BullMQ job via
next_action_at. - Recovery: due runs are scanned every 10 s. Runs continue even if the worker restarts or Redis jobs are lost.
- Segment and schedule triggers: scanned every 60 s under a Redis lock.
- Signals: events (
/v1/.../events) drive triggers, exit rules, goals andwait_untilconditions. Delivery events (delivered, clicked …) also reach runs as signals. - Webhook events:
journey.entered,journey.step_completed,journey.completed,journey.exited(webhooks.md). - Retention: finished runs are deleted once the delivery retention period (
deliveries) expires; expired in-app grants are also cleaned up. When a user is deleted, the user's runs and grants are deleted as well.
API
Dashboard (session) endpoints live under internal/v1/apps/:appId/journeys/…. Public endpoints expose the same paths under v1/apps/:appId/journeys/….
| Method | Path | Scope |
|---|---|---|
| GET | /journeys, /journeys/:id, /journeys/:id/versions, /journeys/:id/stats, /journeys/:id/runs, /journeys/:id/runs/:runId | analytics:read |
| POST/PATCH/DELETE | /journeys, /journeys/:id, PUT /journeys/:id/draft, PATCH /journeys/:id/nodes/:nodeId | admin |
| POST | /journeys/:id/publish, pause, resume, archive, duplicate | admin |
| POST | /journeys/:id/runs (entry via API: external_id / user_id / alias, context) | notifications:write |
| DELETE | /journeys/:id/runs/:runId (exit the run) | admin |
| GET | /users/by/:label/:value/journeys | analytics:read |
The run trigger response has the form {entered, run, reason}. If entry is rejected, reason is one of: inactive, outside_schedule, re_entry, already_active, unknown_user.
SDK: Node hs.journeys.*, PHP $client->journeys() (sdk/node.md, sdk/php.md).
Example: sign-up → purchase reminder
trigger(event: signup) → wait(1 day) → condition(event: purchase):
yeshandle:exitnohandle:send_push→wait(3 days)→send_email
This flow is verified in a time-accelerated acceptance test (apps/worker/src/__tests__/journeys.int.test.ts).
AI site search
A search box embedded in your website: visitors search your own content and, when they ask a question, get a short answer with sources from the pages found. Available on Growth and above…
Decision engine
Picks the best option for each user by learning from behavior. An A/B test picks a single winner; the decision engine sees the differences between user groups and keeps learning.