PushizoDocs
Journeys

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

StatusMeaning
draftNever published; can be deleted.
activeLive; new entries are accepted and runs progress.
pausedNo new entries; waiting runs are held; continues with resume.
archivedPermanently 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 trigger node, 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 completed at 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

TypeDataHandles
triggertrigger.kind: event (+property_filters), segment_enter, api, schedule (segment_id, 5-field cron, timezone)next
waitwait.mode: duration (seconds), until_time (HH:MM, user/app time zone), until_date (at)next
wait_untilconditions[]: event, segment_enter, message (node_id + event) and timeout_secondscond_0…cond_n, timeout
time_windowwindows[] (days 0=Sunday…6, start, end) and time zone; if outside the window, waits until the next windownext
conditionrule: segment, filters (segment AST), message (event of an upstream send), event (within_days)yes, no
ai_decisionagent_id, arms[]. The decision agent picks the best option for the user; it does not send a message (ADR-0074)options and none
channel_decisionchannels[] (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
splitbranches[] (id, percent; total 100). Assignment is deterministic via run_id (FNV-1a)branch IDs
send_push / send_email / send_smstemplate_id or inline contentnext
send_in_appin_app_message_id, expires_secondsnext
webhookurl, headers, Liquid body (POST only)next
update_tagstags (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 messages record with the fields source = journey and journey_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 skipped and the run continues.
  • Quiet hours and frequency caps apply; you can exempt a journey with settings.quiet_hours_exempt and frequency_cap_exempt.
  • send_in_app gives the user a time-limited display grant (in_app_journey_grants). In-app messages with journey_only: true are shown only to users who have this grant.
  • The body of a webhook node is written in Liquid; user, journey, run and context (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.

Settings (settings)

FieldDescription
re_entry.modenever (default), after_exit, after_days (+days)
only_new_usersFor segment triggers, only users who enter the segment after publishing
exit_rules[]event, segment_enter, segment_exit, unsubscribed, became_active
exit_tagsTags to write on exit (rule, goal, exit node)
goals[], exit_on_goalGoal event/segment; conversion rate statistics
schedule.start_at / end_atThe window in which new entries are accepted
quiet_hours_exempt, frequency_cap_exemptExemption 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 and wait_until conditions. 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/….

MethodPathScope
GET/journeys, /journeys/:id, /journeys/:id/versions, /journeys/:id/stats, /journeys/:id/runs, /journeys/:id/runs/:runIdanalytics:read
POST/PATCH/DELETE/journeys, /journeys/:id, PUT /journeys/:id/draft, PATCH /journeys/:id/nodes/:nodeIdadmin
POST/journeys/:id/publish, pause, resume, archive, duplicateadmin
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/journeysanalytics: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):

  • yes handle: exit
  • no handle: 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).

On this page