Skip to main content
Journeys let you automate multi-step messaging sequences that respond to what contacts do. When a trigger fires — a contact is upserted via API, a tag is added, or an external system calls the trigger endpoint — the journey runs its defined steps for that contact: waiting, branching, sending templates, and updating contact data.

​
What a journey does

A journey defines a path a contact travels through over time. Each step in the path is a node. Nodes execute in order, and some nodes pause execution or route the contact down different branches based on conditions. A single journey can run for a contact over hours or days.
A journey processes one contact at a time. If the same trigger fires for multiple contacts simultaneously, each contact runs through the journey independently.

​
Journey triggers

Every journey starts with a trigger — the event that enrolls a contact and starts the first node.
External systems can trigger a journey by calling the compatibility endpoint. This is the most common trigger for CRM integrations, checkout flows, and other backend events.
curl -X POST https://your-switchbord.example.com/compat/journey-trigger/welcome-flow \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "properties": {
      "first_name": "Jane"
    }
  }'
The path segment (welcome-flow in the example) maps to the journey’s configured trigger path. Properties in the payload are merged into the contact’s attributes before the journey runs.See the API Reference for the full endpoint specification and versioned alternatives.
A journey can fire when a specific contact attribute is set or changes to a particular value. Use this to react to data updates from your CRM or external systems.
A journey can fire when a specific tag is added to a contact. Use this to trigger onboarding flows, loyalty sequences, or any other tag-based segmentation logic.
You can manually enroll a single contact into a journey from the contact detail view. Use this for testing or one-off re-engagement.

​
Journey nodes

Nodes are the building blocks of a journey. You add, connect, and configure them in the journey builder canvas.

Send template

Sends an approved WhatsApp template to the contact. You select the template and configure variable values — either static text or mapped from contact attributes.

Wait

Pauses the journey for a specified duration before moving to the next node. Common values are 1 hour, 24 hours, or 3 days.

Branch

Evaluates a condition and routes the contact down one of two paths: a “yes” branch or a “no” branch. Conditions can check contact attributes, tags, or the delivery status of a previous template send.

Update attribute

Sets a custom attribute on the contact. Use this to record journey progress, update lifecycle stage, or store values for use in later steps.

Add tag

Adds a tag to the contact. Tags can trigger other journeys, filter campaign audiences, or mark contacts for inbox triage.

Remove tag

Removes a tag from the contact. Use this to move contacts out of a segment or prevent them from re-entering a journey.

​
Send template node

The Send template node delivers a single approved template to the contact. Before the message is queued, Switchbord validates that the template is still approved and that the contact is not opted out. If the contact has unsubscribed or is blocked, the node fails gracefully and the journey records the skip.
Template sends inside journeys follow the same eligibility rules as inbox sends: the template must be Approved, and the contact must not be unsubscribed or blocked. See the Templates guide for details.

​
Wait node

The Wait node pauses the journey for a fixed duration. The contact sits in a waiting state until the timer expires, then moves to the next node. If you unpublish or edit the journey while a contact is waiting, see Versioning below for how that affects in-progress contacts.

​
Branch node

The Branch node evaluates a single condition and routes the contact to one of two downstream paths. You can branch on:
  • A contact attribute value (e.g., plan = "pro")
  • Whether a tag is present
  • The delivery status of the most recent Send template node (e.g., delivered, failed)
Each branch path continues independently with its own sequence of nodes.

​
Building a journey

1

Open Journeys

Navigate to Journeys in the sidebar and click New journey.
2

Name and configure the trigger

Give the journey a name and select the trigger type. For a REST trigger, set the trigger path (e.g., welcome-flow). This path is the segment used in the API call.
3

Add nodes

Click the + button below the trigger to add the first node. Select the node type and configure it. Repeat to build the full sequence.
4

Connect branches

For Branch nodes, define the condition and connect both the “yes” and “no” outputs to downstream nodes. Every branch output must connect to something — a node or an end marker.
5

Validate

Click Validate to check for configuration errors: missing template selections, disconnected branches, or empty wait durations. Fix any errors before publishing.
6

Publish

Click Publish to make the journey live. Only published journeys process new trigger events. The journey version is recorded at publish time.

​
Publishing

A journey must be published before it processes any contacts. Draft journeys are saved but inactive — triggers that fire for a draft journey are ignored. After you publish, any changes you make put the journey back into a draft state. To apply your changes, publish again. Contacts already running through the journey continue on their current version (see Versioning below).
Publishing a new version of a journey does not automatically migrate contacts who are mid-journey. They continue on the version they started on. Plan breaking changes carefully, or manually re-enroll contacts if needed.

​
Versioning

Switchbord tracks journey versions. Each time you publish, a new version is created. Contacts enrolled before the new publish continue running on their original version until they complete or you force-migrate them. New enrollments always start on the latest published version. This means you can safely iterate on a journey without disrupting contacts who are already mid-flow.

​
Triggering via API

Any system that can make an HTTP POST request can trigger a journey. The compatibility endpoint accepts a phone number and an optional properties map: 
curl -X POST https://your-switchbord.example.com/compat/journey-trigger/welcome-flow \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "properties": {
      "first_name": "Jane"
    }
  }'
The phone field must be in E.164 format. Properties in the payload are merged into the contact record before the journey starts, so nodes that reference contact attributes see the updated values immediately. See the API Reference for versioned endpoints and authentication requirements.