> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Example app: Journeys

> The seven Journeys in the Clean Beans example app: onboarding, streaks, re-engagement, promos, and a Journey webhook that calls the backend.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), which follows one real app from end to end. The app is **Clean Beans**, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend.

Most of the messages in this guide are sent by the backend, one request at a time. A **Journey** is different. It is a sequence built in the OneSignal dashboard that decides for itself who to message, when, and what happens next. Clean Beans uses Journeys for anything that unfolds over hours or days, and for copy and timing that should be changeable without a release.

Clean Beans runs seven Journeys.

| Journey | Starts when | What it does |
| - | - | - |
| [Onboarding](#onboarding-a-sequence-with-a-goal) | The app sends `signed_up` | Welcome email and in-app walkthrough, then three pushes over six days, until the first cleaning session |
| [Session reminder](#session-reminder-start-on-one-event-cancel-on-another) | The app sends `cleaning_session_started` | A push three hours later, unless the session was finished |
| [Session completed](#session-completed-personalize-from-the-event) | The app sends `cleaning_session_completed` | A push to the cleaner naming the room they just cleaned |
| [Room-based promos](#room-based-promos-branch-on-an-event-property) | A recently active member completes a session | A different push for a kitchen, a bathroom, or a bedroom, two hours later |
| [Streak milestone](#streak-milestone-an-event-with-a-number) | The app sends `streak_milestone` | A push celebrating 3, 7, 14, 30 days and beyond |
| [Streak about to break](#streak-about-to-break-timing-a-segment-check-and-varied-copy) | The app sends `cleaning_session_completed` | A warning push the next evening, with one of five wordings |
| [Re-engagement](#re-engagement-and-the-journey-webhook) | A member has been inactive for seven days | Push, push, email, push over ten days, then a webhook to the backend |

None of them has backend code of its own, apart from the webhook at the end of the last one. The app's job is to give the Journeys something to work with.

## What the app gives a Journey to work with

A Journey can see three things about a person: the **custom events** they have sent, their **tags**, and the **segments** they belong to. It cannot read your database. Anything a Journey needs to react to has to arrive in one of those forms.

| Signal | Kind | Sent when | Used by |
| - | - | - | - |
| `signed_up` | Custom event | A new account signs in for the first time | Onboarding (entry) |
| `cleaning_session_started` | Custom event | A cleaning session begins | Session reminder (entry) |
| `cleaning_session_completed` | Custom event, with `room_name` | A cleaning session ends | Session completed, Room-based promos, Streak about to break (entry). Onboarding, Session reminder, Re-engagement (exit) |
| `streak_milestone` | Custom event, with `streak_count` | A session takes the streak to a milestone | Streak milestone (entry) |
| `user_name`, `household_name`, `streak_count` | Tags | Sign-in, session end, profile edit | Personalizing message text |
| `streak_reminders` | Tag | Sign-in, and when notification settings are saved | Streak about to break (who may be sent it) |

The session events are covered in [Tags, custom events, and Conversion Metrics](https://documentation.onesignal.com/docs/en/example-full-integration-tags-events.md). The other two events exist only to start a Journey.

`signed_up` fires once per account. The account's age is checked first, so someone who installs the app on a new phone is not onboarded a second time.

```typescript src/lib/onesignalSync.ts theme={null}
const accountAgeMs = Date.now() - new Date(profile.created_at).getTime();
if (accountAgeMs <= NEW_SIGN_UP_WINDOW_MS) {
  const ctx = await getEventContext();
  if (!ctx) return;

  OneSignal.User.trackEvent('signed_up', {
    external_id: ctx.external_id,
    user_name: ctx.user_name,
    household_name: ctx.household_name,
  });
  console.log('[onesignalSync] Custom event: signed_up');
}

await AsyncStorage.setItem(flagKey, '1');
```

`streak_milestone` carries the streak length as a number, so the message can show it.

```typescript src/lib/onesignalSync.ts theme={null}
OneSignal.User.trackEvent('streak_milestone', {
  external_id: ctx.external_id,
  user_name: ctx.user_name,
  household_name: ctx.household_name,
  streak_count: streak,
});
```

> [!WARNING]
>
> Send an event that starts a Journey only after `OneSignal.login()` has been called. An event sent before login is recorded against an anonymous user, not the person who is about to sign in. Clean Beans calls `trackSignedUpOnce()` straight after `login()` in the same effect. See [SDK setup and user identity](https://documentation.onesignal.com/docs/en/example-full-integration-sdk-setup.md#tie-each-device-to-a-user).

## Onboarding: a sequence with a goal

The onboarding Journey has one aim, which is to get a new member to their first cleaning session. Everything in it stops the moment that happens.

**1. The app sends signed\_up**

The member enters the Journey. Each member goes through once.

**2. A welcome email and an in-app walkthrough go out straight away**

The email lists three steps to get going. The in-app message is shown the next time the member opens the app.

**3. Three pushes follow on days 1, 3, and 6**

Each one waits for a time window of 10:00 to 19:00 in the member's own time zone.

**4. A completed session ends it**

The Journey's exit rule is the `cleaning_session_completed` event. Nobody is nudged to do something they have already done.

| Step | When | Message |
| - | - | - |
| Email | Immediately | "Welcome to Clean Beans", with three steps to get started |
| In-app message | Next app open, for up to three days | The welcome walkthrough |
| Push 1 | Day 1 | "Ready for your first clean?" |
| Push 2 | Day 3 | "Cleaning is easier shared" (opens the Household screen) |
| Push 3 | Day 6 | "Your rota is waiting" |

**Dashboard setup.** Create the Journey with **Custom Event** as its entry rule and `signed_up` as the event. Under exit rules, choose to exit when a custom event occurs and pick `cleaning_session_completed`. Put a **Time Window** step before each push so a wait that ends at 03:00 does not send at 03:00.

> [!TIP]
>
> Choose the goal first and make it the exit rule. A sequence without one keeps talking to people who have already done what it asked.

## Session reminder: start on one event, cancel on another

If someone starts a cleaning session and never finishes it, their work is not logged. This Journey starts on `cleaning_session_started`, waits three hours, and sends a reminder. Its exit rule is `cleaning_session_completed`, so finishing the session cancels the reminder.

| Step | Setting |
| - | - |
| Entry | Custom event `cleaning_session_started` |
| Wait | 3 hours |
| Time window | 08:00 to 21:00, member's time zone |
| Push | "What happened? It looks like you started a cleaning session and didn't finish it." |
| Exit | Custom event `cleaning_session_completed` |

This start-and-cancel pair is the simplest useful Journey there is. The same shape fits an abandoned basket, an unfinished sign-up form, or a draft that was never sent.

> [!NOTE]
>
> **Check the edge of the time window.** The window originally closed at 18:00. A session started at 16:00 would reach the end of its wait at 19:00, find the window shut, and be told "you didn't finish" at 08:00 the next morning. The window now closes at 21:00. When a message only makes sense on the same day, check what happens to someone who arrives just after the window closes.

## Session completed: personalize from the event

When a session ends, the cleaner gets a short confirmation that names the room. The room is not a tag. It comes from the event that started the Journey.

```text Push template: Cleaning Session Completed theme={null}
{{ journey.first_event.properties.room_name }} cleaned ✅

Great work cleaning the {{ journey.first_event.properties.room_name }} {{ user_name | default: 'cleaner' }}! Keep up the hard work!
```

`journey.first_event.properties` reads a property of the entry event. `user_name` on its own reads a tag, and the `default` filter covers anyone whose tag is missing.

This Journey is one step long. It could have been a backend send, like the push that tells housemates about the same session in [Sending push from your backend](https://documentation.onesignal.com/docs/en/example-full-integration-backend-push.md#session-completed-a-push-triggered-from-the-app). It is a Journey because the wording can then be changed, tested, or switched off in the dashboard.

> [!WARNING]
>
> The Event Stream reports a Journey message as it was written, with the Liquid still in it. The Clean Beans inbox showed `{{ journey.first_event.properties.room_name }} cleaned` until the webhook learned to render it. See [Render Liquid before you store it](https://documentation.onesignal.com/docs/en/example-full-integration-inbox.md#render-liquid-before-you-store-it).

## Room-based promos: branch on an event property

This Journey sends a different message depending on which room was cleaned. It shows two things: holding people until an event happens, and branching on a property of that event.

Members enter from a segment of people active in the last seven days. The first step is a **Wait Until** with three branches. Each branch waits for `cleaning_session_completed` with a particular `room_name`.

| Branch condition | Then |
| - | - |
| `room_name` is `Kitchen` | Wait 2 hours, time window 08:00 to 20:00, kitchen push |
| `room_name` is `Bathroom` | Wait 2 hours, time window 08:00 to 20:00, bathroom push |
| `room_name` is `Bedroom` | Wait 2 hours, time window 08:00 to 20:00, bedroom push |

A session in any other room matches no branch, and the member keeps waiting. Re-entry is allowed after 30 minutes, so the Journey responds to each new session.

> [!NOTE]
>
> The pushes in this Journey advertise made-up cleaning products. They are there to show the pattern. They are also marketing messages that the app's notification settings do not cover, which is something to design for in a real app. See [What Journeys cannot see](#what-journeys-cannot-see).

## Streak milestone: an event with a number

The app decides when a streak has reached a milestone, because it has just saved the new streak. It sends `streak_milestone` with the length, and the Journey does the rest.

```text Push template: Streak - Milestone reached theme={null}
🔥 {{ journey.first_event.properties.streak_count }}-day streak!

Nice work, {{ user_name | default: 'you' }}. That's {{ journey.first_event.properties.streak_count }} days in a row. Keep it going tomorrow.
```

| Step | Setting |
| - | - |
| Entry | Custom event `streak_milestone` |
| Wait | 1 minute |
| Push | The template above |

> [!NOTE]
>
> **Two Journeys, one moment.** A milestone always happens at the end of a session, which is also when the session-completed Journey sends. Without the one-minute wait, the two pushes would arrive together. When several Journeys start from the same user action, look at them side by side.

## Streak about to break: timing, a segment check, and varied copy

A streak ends at midnight on any day without a session. This Journey warns the member that evening. It is the most involved of the seven, and each of its steps solves a separate problem.

| Step | Setting | Why |
| - | - | - |
| Entry | Custom event `cleaning_session_completed` | Every session starts a new countdown |
| Wait | 22 hours | See below |
| Time window | 18:00 to 22:00, member's time zone | The evening of the day after the session |
| Yes/No branch | In segment "Streak 2+ Days, Reminders On" | Only people with a streak, who want the reminder |
| Split, 5 branches at 20% | One of five push templates | The wording changes from evening to evening |
| Exit | Custom event `cleaning_session_completed` | They cleaned again, so the warning is no longer true |

**Landing on the right evening.** The warning belongs on the evening after the last session, whatever time that session was. A wait of 22 hours followed by an 18:00 to 22:00 window always lands there. A session at 08:00 reaches the window step at 06:00 the next day and is held until 18:00. A session at 23:00 reaches it at 21:00 the next day and sends at once.

**Respecting a setting the Journey cannot see.** Clean Beans has a "Streak reminders" switch in its notification settings, stored in the database. The app mirrors it as a tag.

```typescript src/lib/onesignalSync.ts theme={null}
// Mirrors the "Streak reminders" setting, so a Journey can respect it.
// Journeys cannot read the app's database, only tags.
streak_reminders:
  profile.notifications_enabled !== false && profile.push_streak_reminders !== false ? 'on' : 'off',
```

The segment requires `streak_count` greater than 1 and `streak_reminders` equal to `on`. A member on an old build has no `streak_reminders` tag at all, so they fall outside the segment and are not sent the warning.

**Varying the copy.** The same sentence every evening is easy to stop seeing. The **Split** step sends each person down one of five branches at random, and each branch has its own template. The branch is chosen again every time someone enters, so a member sees different wording on different evenings.

| Branch | Title |
| - | - |
| A | Your streak ends at midnight |
| B | Don't let your streak slip away |
| C | Still time to clean today |
| D | One task saves your streak |
| E | Midnight is coming for your streak ⏰ |

> [!NOTE]
>
> Clean Beans also shows a streak warning as a Live Activity, described in [Live Activities](https://documentation.onesignal.com/docs/en/example-full-integration-live-activities.md). A member with Live Activities switched on gets both. The push covers Android and anyone who has turned Live Activities off.

## Re-engagement and the Journey webhook

The last Journey handles members who have stopped opening the app. It is the only one that enters from a segment alone, and the only one that calls the backend.

| Step | When | Message |
| - | - | - |
| Entry | The member joins the "Inactive 7+ Days" segment | New entrants only |
| Push 1 | Next 10:00 to 19:00 window | "It's been a while" |
| Push 2 | 2 days later | The weekly leaderboard |
| Email | 3 days later | "We saved your spot" |
| Push 3 | 3 days later | "A fresh start" |
| Webhook | 2 days later | Tells the backend the member has lapsed |
| Exit | Custom event `cleaning_session_completed` | They came back |

Re-entry is allowed after 30 days. The entry is limited to people who join the segment after the Journey starts. Without that, everyone already inactive on the day it is switched on receives the first push at once.

### Tell your backend when the sequence runs out

A member who reaches the end without cleaning has not responded to four messages. A fifth is unlikely to help. Clean Beans tells the household instead. A **Webhook** step calls a backend function, which marks the member as inactive and notifies the household's owners and admins.

**Dashboard setup.** Create a Journey webhook with these settings and select it in the Journey's last step.

```json Journey webhook theme={null}
{
  "method": "POST",
  "url": "https://YOUR_PROJECT_REF.supabase.co/functions/v1/journey-webhook",
  "headers": {
    "Content-Type": "application/json",
    "X-Webhook-Secret": "YOUR_SHARED_SECRET"
  },
  "body": {
    "event": "member_lapsed",
    "external_id": "{{ user.external_id }}"
  }
}
```

The function checks the secret before anything else. It is deployed without Supabase's token check, because OneSignal does not send a Supabase token, so the shared secret is the only thing standing between the endpoint and the public internet.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const secret = req.headers.get('X-Webhook-Secret') ?? '';
if (!JOURNEY_WEBHOOK_SECRET || secret !== JOURNEY_WEBHOOK_SECRET) {
  return new Response('Unauthorized', { status: 401 });
}
```

It then checks the claim for itself. The Journey says the member is inactive, but the Journey only knows about app sessions and events. The database knows whether they have cleaned.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const since = new Date(Date.now() - RECENT_ACTIVITY_DAYS * 24 * 60 * 60 * 1000).toISOString();
const { count: recentSessions } = await supabase
  .from('cleaning_sessions')
  .select('id', { count: 'exact', head: true })
  .eq('user_id', userId)
  .gte('completed_at', since);

if ((recentSessions ?? 0) > 0) {
  return jsonResponse({ skipped: true, reason: 'recently_active' });
}

// Already flagged: a retried or repeated webhook does nothing more
if (profile.lapsed_at) {
  return jsonResponse({ skipped: true, reason: 'already_lapsed' });
}
```

Only then does it mark the member and send one push to the people who can do something about it.

```typescript supabase/functions/journey-webhook/index.ts theme={null}
const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  include_aliases: { external_id: recipientIds },
  target_channel: 'push',
  ...DELIVERY.member_lapsed,
  headings: { en: `${memberName} has gone quiet` },
  contents: { en: `${memberName} hasn't cleaned in a while. A friendly nudge might help.` },
  url: 'cleaning-rota:///household',
  data: { type: 'member_lapsed', memberId: userId, memberName },
};
```

The flag clears itself. A database trigger removes it the next time the member completes a session, so the app never has to remember to.

> [!TIP]
>
> A webhook step can do anything a message step cannot: update a record, open a support ticket, add someone to a list in another system. Treat the request like any other call from outside. Check a secret, check the facts, and make a repeat harmless.

## What Journeys cannot see

Every backend send in this guide checks the member's notification settings before it sends. A Journey cannot do that, because the settings are in the app's database.

| The Journey needs to know | How Clean Beans tells it |
| - | - |
| Something just happened | A custom event |
| A fact about the person | A tag |
| A group of people | A segment built from tags or activity |
| Whether to stop | An exit rule on a custom event |
| A setting stored in your database | A tag that mirrors the setting, and a segment that requires it |

Only the streak warning has a mirrored setting. The other Journey pushes go to anyone with push notifications switched on for the app. If your app has per-type notification settings, mirror each one that a Journey should respect.

## Things to know

* **Look for Journeys that share an audience.** Clean Beans briefly had two re-engagement Journeys live on the same segment, which put every inactive member in line for both sequences. A second Journey on a segment is easy to switch on and hard to notice.
* **Give Journey pushes a URL and a `data.type`.** Templates created in the dashboard have neither by default, so a tap only opens the app. Clean Beans sets both on every Journey template, so they route like the backend's pushes. See [Deep links and notification clicks](https://documentation.onesignal.com/docs/en/example-full-integration-deep-links.md).
* **An active Journey can be edited, and the edit can affect people already in it.** Clean Beans changed a time window and added a wait on Journeys that were running. Make changes like that deliberately.
* **Journey messages count in the inbox.** They arrive through the same Event Stream as every other push, with their Liquid unrendered.
* **Turn off click tracking on an email whose button is a Universal Link.** Tracking rewrites links to pass through a tracking domain, and a rewritten link no longer opens the app. See [Open the app from ordinary web links](https://documentation.onesignal.com/docs/en/example-full-integration-deep-links.md#open-the-app-from-ordinary-web-links).

> [card] [Journeys overview](https://documentation.onesignal.com/docs/en/journeys-overview.md)
>
> Entry rules, steps, and how a Journey runs.

> [card] [Journey settings](https://documentation.onesignal.com/docs/en/journeys-settings.md)
>
> Who enters, exits, and re-enters.

> [card] [Journey actions](https://documentation.onesignal.com/docs/en/journeys-actions.md)
>
> Wait, Wait Until, Yes/No, Split, and Time Window.

> [card] [Journey webhooks](https://documentation.onesignal.com/docs/en/journeys-webhook.md)
>
> Call your own server from a Journey step.

> [card] [Personalize with custom events](https://documentation.onesignal.com/docs/en/personalization-custom-event.md)
>
> Use event properties in Journey messages.

> [card] [Event-driven Journeys](https://documentation.onesignal.com/docs/en/event-driven-journeys.md)
>
> Design Journeys that respond to behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.