Creating a Journey

This guide walks you through building and activating a customer journey in SignalSmith, from naming your journey to launching it for your audience.

Prerequisites

Before creating a journey, ensure you have:

• A SignalSmith workspace with Admin or Editor permissions
• At least one audience defined (for audience-based entry) or an events source configured (for event-based entry)
• At least one destination configured (for action tiles)

Step-by-Step Guide

Step 1: Create a New Journey

1. Navigate to Journeys in the left sidebar
2. Click Create Journey in the top-right corner
3. Enter a descriptive name for your journey (e.g., “New Customer Onboarding”, “Cart Abandonment Recovery”, “Win-Back Campaign”)
4. Optionally add a description explaining the journey’s purpose and target audience

The journey opens in the canvas editor in Draft state. No customers are processed while the journey is in draft.

Step 2: Define Entry Criteria

Every journey starts with an Entry tile, which is automatically placed on the canvas. Click it to configure how customers enter the journey.

Audience-Based Entry

Customers enter the journey when they join a specified audience:

1. Select Audience membership as the entry type
2. Choose the audience from the dropdown (e.g., “High-Value Customers”)
3. Choose whether existing audience members should enter immediately or only new members going forward

This is the most common entry type. Customers enter once — if they leave and rejoin the audience, they do not re-enter unless you enable re-entry.

Event-Based Entry

Customers enter the journey when they trigger a specific event:

1. Select Event trigger as the entry type
2. Choose the event name (e.g., cart_abandoned, signed_up, subscription_cancelled)
3. Optionally add property filters (e.g., cart_value > 50)

Event-based entry allows the same customer to enter the journey multiple times (e.g., each time they abandon a cart), unless you configure re-entry limits.

Manual Entry

Customers are added to the journey manually or via the API:

1. Select Manual as the entry type
2. After activating the journey, use the Add Members button or the API to add specific customer IDs

Manual entry is useful for one-time campaigns, VIP experiences, or testing.

Step 3: Add Tiles to the Canvas

With the entry configured, build your journey by adding tiles from the tile palette on the left side of the canvas. Drag tiles onto the canvas to add them.

A typical onboarding journey might look like:

Entry → Wait (1 day) → Action (Send welcome email)
                              ↓
                     Wait (3 days)
                              ↓
                     Branch (Opened email?)
                      ↓              ↓
                    Yes              No
                      ↓              ↓
              Action (Send         Action (Send
              feature guide)       reminder email)
                      ↓              ↓
                     Exit           Wait (2 days)
                                      ↓
                                    Exit

To add a tile:

1. Click the + button on the canvas or drag a tile type from the palette
2. Click the tile to open its configuration panel
3. Fill in the required settings (see Tile Types for details on each type)

Step 4: Connect Tiles

Tiles are connected by edges that define the flow direction:

1. Hover over a tile to reveal the connection handle (a small circle on the bottom edge)
2. Click and drag from the handle to the next tile
3. Release on the target tile to create the connection

Connection rules:

• Every tile (except Exit) must have at least one outgoing connection
• Branch tiles have multiple outgoing connections — one per branch condition
• Entry tiles cannot receive incoming connections
• Exit tiles cannot have outgoing connections
• You cannot create circular loops (journeys are directed acyclic graphs)

Step 5: Set Exit Criteria

Exit criteria define conditions under which customers should leave the journey early, regardless of their current position on the canvas.

1. Click the Journey Settings gear icon in the top-right of the canvas
2. Under Exit Criteria, click Add Condition
3. Define the exit condition:
   • Audience exit — Customer leaves a specified audience
   • Event trigger — Customer performs a specific action (e.g., purchase_completed)
   • Trait condition — A customer trait changes to match a condition
   • Time limit — Customer has been in the journey longer than a specified duration

You can add multiple exit criteria. A customer exits if any condition is met.

Step 6: Configure Journey Settings

In the Journey Settings panel, you can also configure:

Step 7: Validate the Journey

Before activating, click Validate to check your journey for issues:

• Every tile must be configured (no empty action tiles)
• All tiles must be connected (no orphaned tiles)
• Branch conditions must be complete (every branch needs a path)
• At least one Exit tile must exist
• Entry criteria must be defined
• Referenced audiences and destinations must exist and be active

Validation errors are displayed inline on the canvas, with affected tiles highlighted.

Step 8: Activate the Journey

Once validation passes:

1. Click the Activate button in the top-right corner
2. Review the activation summary:
   • Entry criteria and estimated initial audience size
   • Number of tiles and connections
   • Active destinations that will receive data
   • Exit criteria
3. Confirm activation

The journey transitions from Draft to Active. Customers begin entering immediately based on your entry criteria.

Using the API

You can create and manage journeys programmatically:

# Create a journey
curl -X POST https://your-workspace.signalsmith.dev/api/v1/journeys \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cart Abandonment Recovery",
    "description": "Re-engage customers who abandoned their cart",
    "entry": {
      "type": "event",
      "event_name": "cart_abandoned",
      "filters": [
        { "property": "cart_value", "operator": "gt", "value": 50 }
      ]
    },
    "tiles": [...],
    "edges": [...],
    "exit_criteria": [
      { "type": "event", "event_name": "purchase_completed" }
    ],
    "settings": {
      "re_entry": true,
      "re_entry_cooldown_hours": 168,
      "quiet_hours": { "enabled": true, "start": "22:00", "end": "08:00" }
    }
  }'
 
# Activate a journey
curl -X POST https://your-workspace.signalsmith.dev/api/v1/journeys/{id}/activate \
  -H "Authorization: Bearer $API_TOKEN"

Common Patterns

Onboarding Sequence

Entry (signed_up event) -> Wait 1 day -> Send welcome email -> Wait 3 days -> Branch on engagement -> Send targeted follow-up or reminder -> Exit

Cart Abandonment

Entry (cart_abandoned event) -> Wait 1 hour -> Branch on purchase completed -> If no: send reminder email -> Wait 1 day -> Branch again -> If no: send discount offer -> Exit

Re-engagement

Entry (inactive audience) -> Send re-engagement email -> Wait 7 days -> Branch on any activity -> If yes: exit. If no: send final offer -> Wait 7 days -> Update profile (mark as churned) -> Exit

Troubleshooting

Next Steps

• Tile types reference — Understand every tile type and its configuration options
• Branching logic — Master conditional routing, percentage splits, and time-based branches
• Execution & monitoring — Track performance after activation