Engagement

Journeys

Journeys are versioned automation graphs. A user enters through a segment or custom-event trigger, then moves through timed steps, branches, percentage splits, pushes, webhooks, goals, and exits.

Journey structure#

A definition has:

trigger: how users enter;
start: the ID of the first node; and
nodes: an object keyed by node ID.

Node IDs may contain letters, numbers, _, and -, up to 80 characters. A journey must contain between 1 and 100 nodes.

Event-triggered example#

POST /v1/journeys

{
  "name": "Abandoned checkout reminder",
  "status": "active",
  "reentry_limit": 2,
  "definition": {
    "trigger": {
      "type": "custom_event",
      "event_name": "checkout.abandoned"
    },
    "start": "wait_one_hour",
    "nodes": {
      "wait_one_hour": {
        "type": "wait",
        "seconds": 3600,
        "next": "still_interested"
      },
      "still_interested": {
        "type": "branch",
        "filter": {
          "all": [
            {"field": "custom_event.purchase", "operator": "not_within_days", "value": 1}
          ]
        },
        "yes": "send_reminder",
        "no": "finished"
      },
      "send_reminder": {
        "type": "push",
        "priority": "normal",
        "interruption_level": "active",
        "content": {
          "title": "Still thinking it over?",
          "body": "Your basket is waiting for you."
        },
        "next": "finished"
      },
      "finished": {"type": "exit"}
    }
  }
}

Custom-event triggers start only when the event is associated with a device that belongs to a known user. Segment triggers require an active segment UUID.

Node reference#

Node	Required values	Behaviour
`wait`	`seconds`, `next`	Pauses for 1 second to 31 days
`wait_until`	parseable `at`, `next`	Pauses until an absolute timestamp
`branch`	segment `filter`, `yes`, `no`	Chooses an edge from current user/device data
`split`	`branches`	Stable percentage choice; weights must total 100
`push`	`content.title`, `content.body`, `next`	Sends push content, optionally with a valid queue priority and `passive`, `active`, `time_sensitive`, or `critical` interruption level
`webhook`	`webhook_id`, `next`	Queues the configured webhook destination
`goal`	graph-specific values	Records achievement in the flow
`exit`	none	Ends execution

Every referenced edge must name an existing node. wait, wait_until, push, and webhook nodes require next. A split needs at least two branches, each with a positive integer weight and valid next node.

Versioning and state#

Creation status can be draft or active. Updates accept draft, active, paused, or archived. Every update creates a new immutable journey version, while existing executions keep the version on which they entered.

reentry_limit is clamped between 1 and 100. It limits how many executions the same user may start for that journey.

GET /v1/journeys
GET /v1/journeys/{journey_id}
PATCH /v1/journeys/{journey_id}
DELETE /v1/journeys/{journey_id}

Deleting archives the journey and cancels active or waiting executions. It does not erase historical versions or results.

Statistics#

GET /v1/journeys/{journey_id}/stats

The response groups execution counts by status:

{
  "journey_id": "c873002e-2a62-46ba-854f-b44ab15364d2",
  "executions": [
    {"status":"active","total":31},
    {"status":"completed","total":418},
    {"status":"cancelled","total":4}
  ]
}

Safe rollout#

Create a draft, validate every edge and referenced resource, and test using an isolated custom event or small segment. Activate only after confirming push copy, delays, timezone assumptions, webhook handling, and re-entry behaviour. Pause first if results look wrong; archive only when the flow should no longer accept or continue executions.