OneSignal Journeys Skill

Purpose

Help the agent design and reason about OneSignal Journeys — multi-step automated messaging flows that deliver push, email, SMS, in-app messages, and web push based on user behavior, time delays, segment membership, or custom events.

This is a reasoning guide, not a script. Synthesize the actual questions, options, and Journey shape based on what the user said.

When to Use

Trigger phrases: "create a journey", "build an automation", "set up a welcome series / onboarding flow", "create a re-engagement / win-back flow", "build an abandoned cart flow", "send a drip campaign", "send a recurring weekly message", "trigger a flow when [event]", "branch users on [behavior]", "send a follow-up if the user doesn't [action]", "improve this Journey", "why is my Journey not entering users".

Lookalike intents that should NOT trigger this skill:

• A single one-off message — use messages skill.
• Reusable message content alone — use templates skill.
• A single Custom Event design question — use custom-events skill.

Key Concepts

A Journey is composed of:

• Settings — name, description, entry rules, exit rules, re-entry rules, schedule, optional Goals (alpha).
• Action steps — Wait (fixed delay), Wait Until (condition + expiration), Time Window (day-of-week / hour gating), Yes/No branch, Split Branch (random A/B/N), Tag User.
• Message steps — Push, Email, SMS, In-App Message, Webhook.

Entry rules are either Segment-based OR Custom Event-based — never both. The choice fundamentally shapes the Journey:

• Segment entry — users enter when they match an audience. Re-entry rules apply.
• Custom Event entry — users enter when an event fires; each event carries properties for personalization. Custom Event Journeys always allow re-entry, and the same user can be in the same Journey multiple times in parallel.

For the full product rules (entry/exit/re-entry behavior, lock-when-live constraints, IAM session rules, plan limits, etc.) read REFERENCE.md.

Decisions That Shape a Journey

Each dimension below has a priority tag — use it to decide what to ask vs assume:

1. Purpose / pattern (Critical) — onboarding, re-engagement, abandoned cart, promotional, recurring, behavioral follow-up, A/B test, limited entry. Pattern picks the well-known shape and pre-fills most other dimensions.
2. Entry rule type (Critical) — Segment-based or Custom Event-based. Mutually exclusive. Custom Event when a discrete user action exists; Segment otherwise.
3. Entry specifics (Critical when not implied by pattern) — which Segment + Excluded Segment, or which Custom Event name + property filter.
4. Channels (Often defaultable) — push, email, SMS, in-app, webhook. Most patterns have default channel mixes (re-engagement: push then email; abandoned cart: push then email then SMS).
5. Step sequence + timing (Often defaultable from pattern) — what messages, in what order, with what waits.
6. Branching (Often defaultable) — Yes/No, Split, Wait Until.
7. Exit rules (Often defaultable) — well-known patterns have well-known exits ("user becomes active" for re-engagement; goal Custom Event for abandoned cart).
8. Re-entry (Often defaultable) — pattern picks: onboarding=No, re-engagement=fixed time, recurring=matches cadence.
9. Schedule (Almost always defaultable) — start now, no end date.
10. Name + description (Almost always defaultable) — suggest a clear name and confirm.

Before Asking — Ground in Tools

Skip the wizard whenever possible. Before any AskUserQuestion call:

• Call list_journeys to detect duplicates of the user's intent (don't recreate "Welcome Series" if it already exists; offer to inspect/duplicate/improve instead).
• If entry is Segment-based or the pattern needs an audience, call list_segments to see what exists. Don't invent a Segment definition the user could pick.
• If entry is Custom Event-based, call list_custom_events to confirm the event name actually exists. Flag missing events as a prerequisite.
• For abandoned cart specifically: a cart_updated and purchase_completed event are usually required — confirm both before designing.

Skip Rules — Apply Silently Before Asking Anything

Before composing any AskUserQuestion call, run this decision table. Anything that resolves here is a silent default: declare it as an assumption in the final summary, don't ask about it.

Only ask about dimensions that none of the above pin down AND the user didn't specify. If everything pins down, skip AskUserQuestion entirely and summarize with assumptions named.

How to Reason About Questions

1. Identify the pattern from the user's prompt. If pattern is unclear, that is the only question for this turn — do not pre-batch the rest. Pattern reshapes everything downstream.
2. Walk Decisions 2–10 mentally; mark each as Specified (user said it), Skip-Rule (resolved by the table above), or Open.
3. Ground in tools — many "Open" dimensions become "Specified" once you've checked existing data (list_custom_events, list_segments, etc.).
4. After grounding, count remaining Open dimensions:

• 0 Open → skip AskUserQuestion. Summarize with every assumption named.
• 1–2 Open → one AskUserQuestion call with exactly that many questions. No filler questions.
• 3–4 Open → one call. Re-check whether any of them is actually Skip-Rule-resolvable; collapse if so.
• 5+ Open → you missed a pattern. Reread the user's prompt; the pattern is probably named or strongly implied.

Question Quality Bar

Apply to every question before including it in a batch:

• Reshape test: would the answer materially change the artifact? If two options produce the same Journey, the question is filler — drop it.
• Concrete options: every option must be a real value (named segment, real event from list_custom_events, specific duration, recommended default). Never use generic placeholders like "Standard" or "Custom" without saying what they map to.
• Mutual exclusivity: if a user could reasonably pick two options at once, the question is multi-select. If they can only pick one, it's single-select.
• Decision-shaped header: the header field should explain why this matters, not restate the question. ("This becomes the exit condition" beats "Goal action".)
• Default-named: when one option is the recommended default for the pattern, mark it: "Push + Email — recommended for onboarding". Don't make the user guess.
• Last option is always free-text: "Type your answer…" (or domain-flavored equivalent like "Describe a different cadence…").
• Order by impact: put the question that bisects the most uncertainty first. The pattern question (when needed) always goes first.

If a candidate question fails any of these, fix it or drop it.

Ambiguity to Watch For

• "welcome series" / "onboarding" / "drip" — pattern is clear but the trigger (signup event vs subscribed-users segment) and goal action usually aren't.
• "re-engagement" / "win-back" — clarify inactivity threshold and goal action.
• "abandoned cart" — needs Custom Event entry on cart_updated AND same event as exit (so cart updates restart the timer); confirm event names exist.
• "recurring" / "weekly" / "every Friday" — needs a Time Window node first + re-entry duration LONGER than the time window. Re-entry too short causes double-sends.
• "A/B test" — Split Branch; locks once live.
• "send only once" / "limited entry" — journey_count tag pattern with audience exclusion at the cap.
• "branch on which button they clicked" — built-in Yes/No can't see button clicks; needs SDK click listener emitting a Custom Event with the action ID.
• "event-driven" — clarify event name(s) and property filters.

Defaults & Best Practices

Apply per-pattern defaults silently and surface them as assumptions in the summary:

• Onboarding: Custom Event entry on signup_completed (fall back to "Subscribed Users" segment + Future additions only if no event), no re-entry, push + email, day-0 / day-2 / day-7 cadence.
• Re-engagement: Segment entry on last_session > N days with mirrored Excluded Segment, exit on "user becomes active", re-entry after N days, push then email.
• Abandoned cart: Custom Event entry on cart_updated with same event as exit, plus purchase_completed exit, push at 1h then email at 24h.
• Recurring: Time Window first, re-entry strictly longer than window duration but shorter than send interval.

Other defaults: After any Tag User step, add a ~15-minute Wait before any webhook/personalized step that depends on the tag. Mix channels — don't stack two pushes back-to-back. Always suggest a clear Journey name.

For full per-pattern recipes and edge cases, read EXAMPLES.md.

Summary and Approval

Every summary must include:

• Journey name + description.
• Pattern.
• Entry rule with specifics.
• Ordered steps in human-readable form.
• Branching logic.
• Exit rules.
• Re-entry rules (when Segment-based).
• Schedule.
• Assumptions — every default you applied so the user can correct them.
• Must-mention warnings for this domain:
• Split Branches lock when the Journey goes live.
• "Future additions only" locks Segments permanently when live.
• IAMs only display once per user per Journey, even on re-entry.
• IAMs require a new session to display (30+ s background then re-open).
• Re-entry duration must exceed time-window duration to prevent double-sends.
• Entry rule type cannot be switched between Segment and Custom Event after going live (requires duplicate).
• Active Journey count is plan-limited.

Require explicit user approval before creating, launching, archiving, or deleting. For edits to a live Journey, call out which changes apply immediately to in-flight users and which apply only to future entrants.

Anti-Patterns

Avoid:

• Mixing Segment and Custom Event entry rules in the same Journey (not supported).
• Suggesting Split Branch edits on a live Journey (locked; require duplication).
• Putting a message step immediately after entry when the audience can match both entry and exit rules — first send goes out before exit. Recommend a Wait or Excluded Segment.
• Designing recurring Journeys with re-entry ≤ time-window duration (double-sends).
• Saying webhooks call OneSignal APIs (they can't) or are rate-limited by OneSignal (they aren't).
• Recommending the same Custom Event fire from both an SDK and a backend without dedup via idempotency_key.
• Sending PII inside Custom Event properties or tags.
• Renaming Custom Events or tags that an existing Journey depends on.
• Reproducing this skill's example wording verbatim — derive your own from the user's prompt.

Supporting Files

• REFERENCE.md — full product rules: entry/exit/re-entry semantics, edit-live behavior, Custom Event mechanics, webhook constraints, IAM rules, plan limits. Read when verifying a constraint or warning the user about a lock.
• EXAMPLES.md — worked reasoning traces (minimal prompt, fully-specified prompt, ambiguous term, channel-not-set-up, user-pushes-back, skip-AskUserQuestion-entirely). Read when the user's request resembles a known pattern.