Skip to main content

Common Journey Patterns

This page describes reusable patterns for building Journeys. Each pattern explains the structure, when to use it, and the key signals and attachments involved. You can combine multiple patterns within a single Journey or across chained Journeys.

Linear Time-Based​

Deliver content on a fixed schedule. Each transition uses a Time trigger to advance the participant after a set delay.

Structure:

When to use: Journeys with a fixed curriculum delivered over days or weeks (e.g. a 4-week education series).

Key configuration:

  • Trigger type: Time (days/hours from reaching the state)
  • Attachments: Add Card on each transition to deliver the next piece of content or activity

Tips:

  • Use Time from Journey Start on the first transition if the first piece of content should be delivered immediately (0 seconds)
  • Keep each Journey module to 1–2 weeks and chain them together for longer Journeys (see Versioning & Modular Design)

Content Completion-Based​

Advance participants only when they read a Content Card. The Journey waits at each state until the participant engages with the content before moving on.

Structure:

When to use: Self-paced education where participants control the speed.

Key configuration:

  • Trigger type: Signal
  • Signal: code == "CONTENT_READ" && identifier == "{cardId}"
  • The Content Card is delivered via an Add Card attachment on the inbound transition

Tips:

  • Combine with a time-based fallback transition (e.g. advance after 7 days even if not read) to prevent participants from stalling indefinitely

Activity Completion-Based​

Advance participants when they complete an Activity Card, regardless of their responses.

Structure:

When to use: Check-in workflows, assessments, or any flow where the act of completing the activity is enough to move forward.

Key configuration:

  • Trigger type: Signal
  • Signal: code == "ACTIVITY_REPORTED" && identifier == "{cardId}"
  • Deliver the Activity Card via Add Card on the inbound transition

Branching via Activity Responses​

Route participants down different paths based on their Activity responses or scores. Create multiple transitions out of a single state, each with a different signal condition.

Structure:

When to use: Triage, assessments, personalised content paths based on participant answers.

Key configuration:

  • Trigger type: Signal
  • Signal examples:
    • By score: code == "ACTIVITY_REPORTED" && identifier == "1" && scores < 5
    • By element value: code == "ACTIVITY_REPORTED" && identifier == "1" && values.READINESS_LEVEL == "Not ready"
    • By multi-select: code == "ACTIVITY_REPORTED" && identifier == "1" && anyof(values.INTERESTS, ["Running", "Swimming"])

Tips:

  • Make sure your branch conditions are mutually exclusive to avoid unexpected behaviour
  • Use scored activities (Sum, Average, etc.) for numeric triage — see Scoring & Triage below

Branching via Messages​

Route participants based on their response to a chat message with response buttons. Send a message with options, then create separate transitions for each possible reply.

Structure:

When to use: Quick decision points, consent checks, or conversational Journeys where the participant chooses a direction.

Key configuration:

  • The message attachment must have response buttons configured (e.g. "Yes" / "No")
  • Trigger type: Chat Message — select the message sent in the previous transition, then choose which response option this transition should match
  • Create one transition per response option, each using the Chat Message trigger pointed at the same message but matching a different response

Tips:

  • Add a time-based fallback transition for participants who don't respond

Message-Based​

A Journey driven entirely by chat messages rather than Cards. Useful for conversational coaching, onboarding questions, or quick check-ins.

Structure:

When to use: Lightweight interactions that don't need a full Activity Card, conversational onboarding, or quick pulse checks.

Key configuration:

  • Attachments: Send Message (Inbox channel) with response buttons
  • Trigger type: Chat Message — select the message from the previous transition, then choose the expected response to advance

Tips:

  • Combine message-based steps with branching to create conversational decision trees
  • Keep message chains short — long sequences can feel tedious; switch to Activity Cards for anything requiring more than 2–3 questions

Loops​

Cycle a participant back to a previous state to create recurring check-ins or repeated content delivery. A transition points back to an earlier state instead of forward.

Structure:

When to use: Weekly check-ins, recurring reflections, habit tracking, or any pattern that repeats on a schedule.

Key configuration:

  • Create a transition from a later state back to an earlier state
  • Use a Time trigger on the looping transition (e.g. 7 days)
  • Add Add Card attachments to re-deliver the check-in activity

Tips:

  • Add an exit condition to break out of the loop (e.g. a tag-based transition, a score threshold, or a time-from-start limit)
  • Without an exit condition, the participant will loop indefinitely — this may be intentional for ongoing Journeys

Listener Sub-Journeys​

A main Journey starts a sub-Journey that adds a recurring Activity Card, listens for each completion, gives feedback, and loops back to listen again. Every time the participant completes the activity, the sub-Journey provides feedback and resets to wait for the next response.

Structure:

The recurring Activity Card is added once and keeps appearing on the participant's schedule. The sub-Journey then loops between listening and giving feedback — it does not re-add the Card each time.

When to use: Ongoing monitoring with automated feedback — mood tracking with encouragement, symptom diaries with tailored responses, exercise logs with progress commentary.

Key configuration:

  • Main Journey: Start Journey attachment to launch the sub-Journey
  • Sub-Journey first transition: Add Card with a recurring schedule to deliver the activity on an ongoing basis (e.g. daily, weekly)
  • Sub-Journey listen transition: Signal with code == "ACTIVITY_REPORTED" && identifier == "{cardId}"
  • Sub-Journey feedback transition: Send Message with contextual feedback (can branch based on values/scores)
  • Sub-Journey loop transition: points back to the waiting state (not the Card delivery state) so the recurring Card continues on its schedule without being re-added

Tips:

  • Use branching within the feedback step to give different messages based on scores or values (e.g. "Great job!" vs "Let's work on this together")
  • The sub-Journey runs independently, so the main Journey can continue delivering other content in parallel
  • Add a Remove Tags or Stop Journey mechanism so coaches can end the listening loop when appropriate

Exception Handling​

Handle edge cases like non-responses, unexpected paths, or timeout scenarios using fallback transitions.

Structure:

When to use: Any Journey where a participant might not respond, or where you need a safety net to prevent participants from getting stuck.

Key configuration:

  • Add a Time trigger transition alongside the signal-based transition from the same state
  • The time-based transition fires only if the signal hasn't fired first
  • Chain reminders: first nudge → second nudge → escalation (coach task or different path)

Common patterns:

  • No response reminder: Time trigger → Send Message with a gentle nudge
  • Escalation: After multiple missed responses, add a Add Task attachment to alert a coach
  • Graceful exit: After extended inactivity, move to an end state with a "We're here when you're ready" message
  • Catch-all transitions: Add a broad signal transition as a fallback if none of the specific branch conditions match

SMS & Email-Based​

Journeys that communicate via SMS, email, or push notifications instead of (or in addition to) in-app messages. Useful for reaching participants who may not open the app regularly.

Structure:

When to use: Appointment reminders, medication adherence nudges, re-engagement campaigns, or populations that prefer SMS/email.

Key configuration:

  • Attachments: Send Message with channel set to SMS, Email, or Push Notification
  • Time-based triggers between messages

Tips:

  • SMS and email messages cannot have response buttons — use them for one-way communication or pair with an in-app activity for responses
  • Consider using a Home Feed Card message type to deliver a message as a Card in the participant's feed
  • Be mindful of SMS costs and frequency — too many messages can feel intrusive

Onboarding​

Welcome flows triggered automatically when a participant is created, signs up, or consents. The Onboarding Journey uses special built-in signals.

Structure:

When to use: Every deployment should have an onboarding Journey to welcome new participants and get them started.

Key configuration:

  • Signal: code == "PARTICIPANT_CREATED" (coach-added) or code == "PARTICIPANT_SIGNED_UP" (self-registered)
  • Signal: code == "PARTICIPANT_CONSENTED" to gate content until consent is given
  • Attachments: Send Message (welcome), Add Card (intro content), Start Journey (enrol in next Journey), Add Tags / Add Groups

Tips:

  • Branch based on how the participant was created (coach-added vs self-registered) to tailor the welcome experience
  • Use the onboarding Journey to assign tags, groups, and extras that other Journeys and Campaigns depend on
  • Keep onboarding short and impactful — deliver the first Card quickly so participants see value immediately

Group, Tag & Extra Conditional Content​

Deliver different Cards, messages, or Journey paths based on a participant's groups, tags, or extras. Use conditions on transitions to personalise the experience.

Structure:

When to use: Multi-cohort Journeys, personalised content delivery, or any scenario where different participants should receive different experiences within the same Journey.

Key configuration:

  • Add conditions to transitions using tags.{TAG_CODE} == "true", groups.{GROUP_CODE} == "true", or extras.{EXTRA_CODE} == "value"
  • Combine with any trigger type (time, signal, or message response)

Examples:

  • tags.HIGH_RISK == "true" — route high-risk participants to intensive content
  • groups.CLINIC_A == "true" — deliver clinic-specific instructions
  • extras.PREFERRED_LANGUAGE == "te reo" — send content in the participant's preferred language
  • extras.MEDICATION == "Metformin" — deliver medication-specific education

Tips:

  • Set tags, groups, and extras during onboarding or via earlier Journey steps so they're available for later conditions
  • Use == "false" in the condition field (not the signal field) to check that a tag or group is absent
  • Combine multiple conditions with && for precise targeting

Scoring & Triage​

Use scored Activity Cards to automatically route participants to the right intensity level. Combine scored activities with branching transitions.

Structure:

When to use: Clinical assessments (PHQ-9, GAD-7, K10), wellness screenings, readiness assessments, or any scenario where a numeric score determines the next step.

Key configuration:

  • Activity scoring strategy: Sum, Average, Min, Max, or Median
  • Signal: code == "ACTIVITY_REPORTED" && identifier == "{cardId}" && scores <= 4
  • Add a Add Task attachment on high-severity branches to alert coaches

Tips:

  • Re-assess periodically by looping back to the assessment state — combine with the Loops pattern
  • Use session variables (vars) to store previous scores and compare over time

Drip-Feed Education​

Deliver a series of content pieces with time gates between each one. Unlike purely time-based delivery, drip-feed combines time delays with completion signals so participants must engage before the next piece unlocks.

Structure:

When to use: Educational courses, onboarding series, or any Journey where you want participants to both engage with content and have time to absorb it before moving on.

Key configuration:

  • First transition: Signal code == "CONTENT_READ" && identifier == "{cardId}"
  • Second transition from same state: Time (2 days) as a minimum gap
  • Combine both by using the signal transition to move to an intermediate "wait" state, then a time transition to deliver the next piece

Tips:

  • Consider adding a reminder message if content isn't read within a few days
  • This pattern works well as a modular sub-Journey that can be reused across Journeys

Nudge & Reminder​

Send reminders when a participant hasn't completed a Card within a set time. Escalate through channels (in-app → push → SMS → coach task) if they continue to be unresponsive.

Structure:

When to use: Critical activities where completion matters — medication adherence, safety check-ins, important milestones.

Key configuration:

  • Each state has two outbound transitions: a Signal for completion and a Time fallback
  • Nudge attachments: Send Message (Inbox), then Send Message (Push Notification), then Send Message (SMS)
  • Final escalation: Add Task to alert a coach

Tips:

  • Keep nudge messages warm and encouraging, not nagging
  • Space reminders further apart with each escalation step
  • Consider a graceful exit rather than endless reminders — "We noticed you've been busy. We're here when you're ready."

Parallel Journeys​

Run multiple Journeys concurrently for the same participant, each handling a different concern or health area.

Structure:

Each Journey runs independently with its own states, transitions, and timing.

When to use: Multi-domain Journeys (e.g. a diabetes Journey covering nutrition, exercise, medication, and mental health simultaneously).

Key configuration:

  • Use Start Journey attachments on a single transition to launch multiple Journeys at once
  • Each sub-Journey is self-contained with its own start and end states

Tips:

  • Be mindful of content volume — three Journeys delivering Cards simultaneously can overwhelm a participant
  • Stagger delivery times across Journeys (e.g. nutrition Cards in the morning, exercise Cards in the afternoon)
  • Use tags to coordinate across parallel Journeys if needed (see Tag-Based Coordination below)

Tag-Based Coordination​

Use tag add/remove signals to coordinate behaviour across multiple Journeys. One Journey adds a tag, and another Journey reacts to it.

Structure:

When to use: Cross-Journey communication, milestone tracking, or triggering secondary workflows based on progress in a primary Journey.

Key configuration:

  • Journey A attachment: Add Tags with the coordination tag
  • Journey B signal: code == "PARTICIPANT_TAG_ADDED" && tags.READY_FOR_PHASE_2 == "true"

Tips:

  • Use descriptive tag names that indicate their purpose (e.g. COMPLETED_MODULE_1, HIGH_RISK_FLAGGED, READY_FOR_DISCHARGE)
  • Clean up coordination tags with Remove Tags when they're no longer needed
  • This pattern is especially powerful with Campaigns — add a tag in one Journey and let a Campaign auto-enrol matching participants in the next

Self-Enrolment from Explore​

Allow participants to browse and start Journeys themselves from the Explore screen in the app. Useful for optional Journeys, elective education, or self-service wellbeing tools.

Key configuration:

  • Enable Self Enrolment on the Journey settings
  • Add a clear name, description, and asset image so participants understand what they're signing up for

When to use: Optional add-on Journeys, wellbeing libraries, or situations where participants should have autonomy over their experience.

Tips:

  • Combine with the Explore screen configuration to feature promoted Journeys
  • Self-enrolment Journeys work well as standalone modules that complement a coach-assigned core Journey
  • Consider using tags to track which optional Journeys a participant has self-enrolled in

Combining Patterns​

Most real-world Journeys combine several patterns. Here are some common combinations:

  • Onboarding + Scoring + Branching: Welcome the participant, run an assessment, and route them to the appropriate intensity level
  • Linear + Loops + Nudges: Deliver weekly education with a recurring check-in and reminders for non-responders
  • Listener Sub-Journey + Tag Coordination: A mood-tracking listener runs in parallel, flags concerning scores with a tag, and the main Journey reacts
  • Drip-Feed + Nudges: Deliver an education series with reminders for participants who haven't engaged with the latest content