Flows

Orbit Flows is a visual workflow builder that lets you design complex communication automations without writing code. Connect triggers, conditions, channels, and AI agents into multi-step workflows using a drag-and-drop interface.

What Are Flows?

Flows are directed graphs of nodes that execute in sequence or parallel based on conditions. Each node performs an action — sending a message, calling an API, running an AI agent, or evaluating a condition.

Trigger → Condition → Send SMS → Wait → Check Response → Branch
                                                           ├── AI Agent
                                                           └── Human Handoff

Core Concepts

Concept	Description
Trigger	What starts the flow — incoming message, API call, schedule, or webhook
Node	A single step in the flow — send message, HTTP request, delay, condition
Edge	Connection between nodes defining execution order
Branch	Conditional logic that splits the flow based on data or responses
Variable	Dynamic data passed between nodes (e.g., user name, order ID)

Use Cases

Welcome series — onboard new users with a multi-step SMS + email sequence
Appointment reminders — send reminders 24h and 1h before, handle confirmations
Lead nurturing — qualify leads with AI, route hot leads to sales
Support escalation — try AI agent first, escalate to human if unresolved
Order updates — notify customers at each stage of fulfillment
Survey collection — send surveys post-interaction, analyze responses with AI

Trigger Catalog

Every flow starts from exactly one trigger. The Flow Builder exposes nine trigger types; each maps to the API trigger_type shown in the right column.

Trigger	What starts the flow	API `trigger_type`
Incoming SMS	An SMS arrives on one of your numbers	`event`
Incoming WhatsApp	A WhatsApp message arrives	`event`
Incoming Email	An email arrives on a connected address	`event`
Webhook	An external system calls the flow’s webhook URL	`webhook`
Schedule	A cron schedule fires (e.g., daily at 9 AM)	`schedule`
Business Event	A platform event fires (e.g., `contact.created`)	`event`
Campaign	A campaign sends to a contact	`event`
Contact Action	A contact is added, updated, or tagged	`event`
Audience Event	A contact enters or leaves an audience	`event`

Two more trigger_type values exist for programmatic starts: manual (the Start Flow API or the dashboard’s Run action) and workflow (started by another flow).

Trigger payloads

When a flow starts, everything the trigger supplies becomes the initial execution context. Keys mentioned below are the ones the runtime wires in itself; inbound routings may add more (for example a keyword hit appends keyword).

Trigger	Payload keys
Incoming message (SMS / WhatsApp)	`message` (body text), `from` (sender), `to` (your number), `channel` (`sms`, `whatsapp`, …)
Schedule	Scheduled fire time; the contact list the schedule iterates
Business Event	`event` (event name) plus the event’s fields (for `contact.created`: the contact record)
Campaign	The contact and campaign identifiers
Webhook / Manual	Whatever JSON the caller POSTed to the webhook URL or Start Flow call

Variables anywhere in the flow resolve against this context plus contact fields, using {{...}} placeholders — flat keys like {{first_name}}, not {{contact.first_name}}. A placeholder whose key is absent renders as an empty string.

Validate a Flow

GET /flows/:id/validate checks a saved flow’s definition for structural correctness without running it. Run it before activation (and before forecasting) so obvious graph problems surface at build time:

curl -X GET "https://api.orbit.devotel.io/api/v1/flows/flw_9f2c1a/validate" \
  -H "X-API-Key: dv_live_sk_..."

The call returns valid and an errors list. Checks include:

The definition has at least one node, and node id + type are present
A trigger node exists
No node is disconnected from every edge
abTest / experiment nodes define at least two variants, and any explicit weights sum to 100
No graph cycle that passes through no delay/wait node (cyclic drip loops that include a wait node are allowed)

{
  "data": {
    "valid": false,
    "errors": [
      "Node 'send_followup' is disconnected",
      "A/B test node 'split_ab' variant weights must sum to 100 (got 80)"
    ]
  }
}

When valid is true, errors is an empty array. The same checks also run automatically on POST /flows and PUT /flows/:id.

Node Taxonomy

Action nodes

Node	Type id	Description
Send SMS, Send WhatsApp, Send Email, Send RCS, Make Call, HTTP Request (`webhook`)	Per-channel send ids	The visual builder’s core palette — one send node per channel, plus voice and outbound HTTP
Messaging extras	`sendViber`, `sendLine`, `sendTelegram`, `sendInstagram`, `sendMessenger`, `sendPush`, `sendFax`	Additional send channels available in API-defined flows
Send Survey	`sendSurvey` (or `send_survey`)	Send an NPS, CSAT, or CES survey to the contact

AI nodes

Node	Type id	Description
Run Agent	`aiAgent`	Hand the conversation to an AI agent — `data.agent_id`
AI Classify	`aiClassify`	Classify the inbound message against a list of intents you supply in `data.intents`, then route on the detected intent
AI Response	`aiResponse`	Generate an AI-written reply from the conversation
AI Sentiment	`aiSentiment`	Score message sentiment (positive / neutral / negative) and branch on it — `data.sentimentPositiveThreshold`, `data.sentimentNegativeThreshold`

Logic nodes

Node	Type id	Description
Condition	`condition`	If/else branch — `data.field`, `data.operator`, `data.value`
Split	`split`	Fork execution down several branches in parallel; `data.waitMode` chooses `all` (wait for every branch) or `any`/`first_success` (stop losers once a winner finishes)
Merge	`merge`	Join parallel branches back into a single path
Delay	`delay`	Wait — `data.amount` and `data.unit` (`seconds`, `minutes`, `hours`, `days`)
Send-Time Optimization	`sto_wait`	Hold the contact until their predicted best time to receive the next message; skipped when the context has no `contact_id`
A/B Test	`abTest` (or `experiment`)	Route each contact deterministically down one weighted variant (sticky per contact) and record the assignment so flow analytics reports a per-variant winner against the flow’s conversion goal

Data nodes

Node	Type id	Description
Functions	`function` (or `transform`)	Derive or set flow variables with safe `{{...}}` templates and boolean expressions, then reference them downstream — recipes in Functions node recipes
Update Record	`updateRecord` (or `updateContact`)	Write collected fields (lifecycle stage, tags, custom attributes) back to the contact record

An unrecognized node type is skipped at runtime: the executor logs it as unhandled and takes the node’s default outgoing edge, so a node does nothing unless its type matches one the executor implements.

Visual builder vs API-only

Everything in the Trigger Catalog above and the Action / AI / Logic core is in the builder’s palette; the builder page lists them with their config panels in Flow Builder. Two categories are API-only today — define them in a flow’s definition.nodes over the API and the runtime executes them identically:

Messaging extras — sendViber, sendLine, sendTelegram, sendInstagram, sendMessenger, sendPush, sendFax
Data + optimization nodes — Functions, Update Record, Send Survey, Send-Time Optimization, A/B Test

Edge Semantics

Each edge connects a source node to a target node and may carry a sourceHandle that says which exit route it represents. The executor picks the next node by handle, not by drawing order:

Node	Handles
`condition`	`yes` (predicate true) / `no` (predicate false)
`aiClassify`	One edge named for each intent in `data.intents`; `yes` is the fallback when no named edge matches; `no` when the classifier produced nothing
`aiSentiment`	`positive`/`yes`, `negative`/`no`, `neutral`
`abTest`	A handle per variant id (e.g. `a`/`b`) — assignment is deterministic per contact, so re-entry re-derives the same variant
Any node	`error` — an explicitly drawn error path; when a node throws, the executor prefers this edge over the default route

When no handle matches, the executor falls back to the node’s unlabeled default edge. When that default is absent too, the run ends there. Every handle-and-fallback decision lands in the step trace the Executions API returns, so a mis-routed branch is inspectable per node.

Where Flows Fire

A flow reaches live traffic through one of these entry points:

Inbound routing rules — match an incoming message by keyword or sender, then start the flow. These rules are configured under the inbound-routing surface (sms_inbound_routes family); the transport split between inbound and outbound paths is covered in Transport architecture.
Webhooks — an external system POSTs the payload to the flow’s webhook URL.
Schedule — a cron schedule you attach as trigger_type: "schedule" with cron_expr and an optional cron_tz.
Campaigns, contact/audience events — platform events and campaign sends start event-triggered flows.
API / dashboard — manual flows start from the Start Flow call or the dashboard’s Run action.

Create a Flow via API

curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "trigger_type": "event",
    "definition": {
      "trigger": {
        "type": "event",
        "event": "contact.created"
      },
      "nodes": [
        {
          "id": "send_welcome",
          "type": "sendSms",
          "data": {
            "to": "{{phone}}",
            "body": "Welcome to Acme, {{name}}! Reply HELP for assistance."
          }
        },
        {
          "id": "wait_1d",
          "type": "delay",
          "data": { "amount": 24, "unit": "hours" }
        },
        {
          "id": "send_followup",
          "type": "sendEmail",
          "data": {
            "to": "{{email}}",
            "body": "Hi {{name}}, here is how to get the most out of Acme."
          }
        }
      ],
      "edges": [
        { "source": "send_welcome", "target": "wait_1d" },
        { "source": "wait_1d", "target": "send_followup" }
      ]
    }
  }'

The top-level body requires name, trigger_type (one of manual, webhook, schedule, event, workflow), and definition — an object holding the flow graph (nodes, edges, and any trigger detail). For trigger_type: "schedule" also supply cron_expr (5-field cron) and an optional cron_tz (IANA timezone, defaults to UTC).

Node shape

Each node has an id, a type, and a data object that carries the node’s settings — the runtime reads node settings from data, not from the node’s top level. Edges connect nodes with source and target (the node ids), plus the optional sourceHandle routing described in Edge Semantics.

Forecast a Flow Before Activation

POST /flows/:id/simulate dry-runs a flow against an audience before you activate it. It projects the per-step drop-off funnel, the channel mix, the predicted send cost, and a conversion estimate — without enrolling a contact, emitting a send, or wiring a provider. The projection is pure; it is a POST only because it carries a body. This is the same call the builder’s Test/Forecast toolbar action uses, so a what-if in the dashboard and an API forecast return the same shape.

curl -X POST "https://api.orbit.devotel.io/api/v1/flows/flw_9f2c1a/simulate" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audience_size": 25000,
    "default_country": "US",
    "assumptions": {
      "expected_conversion_rate": 0.04
    }
  }'

Body fields (all optional except that one of the audience inputs is required):

Field	Meaning
`audience_size`	Explicit audience count to model
`list_id`	Contact list whose member count seeds the audience (used when `audience_size` is omitted)
`default_country`	ISO alpha-2 destination used to price projected sends; `"*"` (default) prices at the wildcard rate
`assumptions`	Retention/conversion overrides — `send_retention_rate`, `delay_retention_rate`, `branch_retention_rate`, `expected_conversion_rate`, `avg_call_minutes` (all optional, each 0–1 except minutes, ≤600)
`use_historical`	When true (default), blend the flow’s real historical drop-off funnel into the projection
`definition`	An unsaved draft definition to forecast instead of the stored one — the builder’s in-flight what-if

The forecast math walks the flow’s nodes in traversal order and applies a retention factor at each step: a sendRetentionRate after send/call nodes, a delayRetentionRate across delay/sto_wait nodes, and a branchRetentionRate as the share continuing the primary path at condition/split/abTest nodes. Defaults are deliberately conservative (0.99 / 0.9 / 0.5); per-request assumptions override them. When use_historical applies, a node’s real step-conversion rate from the analytics funnel (below) overrides the assumption for that node. Response (excerpt):

{
  "data": {
    "flow_id": "flw_9f2c1a",
    "audience_size": 25000,
    "audience_source": "explicit",
    "entered": 25000,
    "completed": 11166,
    "completion_rate": 0.4466,
    "predicted_conversions": 447,
    "predicted_conversion_rate": 0.0179,
    "used_historical": true,
    "steps": [
      {
        "node_id": "send_welcome",
        "node_type": "sendSms",
        "channel": "sms",
        "reached": 25000,
        "dropped_off": 0,
        "step_retention_rate": 0.97,
        "overall_conversion_rate": 1,
        "sends": 25000,
        "from_history": true
      }
    ],
    "channel_volume": [{ "channel": "sms", "sends": 25000 }],
    "cost": {
      "currency": "USD",
      "default_country": "US",
      "channels": [
        { "channel": "sms", "sends": 25000, "units": 25000,
          "unit_price_cents": 30, "projected_cost_cents": 750000 }
      ],
      "total_projected_cost_cents": 750000
    },
    "assumptions": { "sendRetentionRate": 0.99, "delayRetentionRate": 0.9 }
  }
}

In each step, step_retention_rate is the factor applied when leaving the node, from_history marks whether it came from real history or an assumption, and sends is the projected send/call count at the node. Send costs are priced through the tenant’s own configured rates for the given default_country, per channel (voice calls are multiplied by avg_call_minutes before pricing). A missing rate yields a zero cost, never an error. The forecast is a read-only estimate — no ledger row is written.

Per-Flow Conversion Analytics

GET /flows/:id/analytics returns the post-activation read of a flow: how many executions entered and completed, a per-node drop-off funnel in traversal order, and how many contacts converted against the flow’s goal.

curl -X GET "https://api.orbit.devotel.io/api/v1/flows/flw_9f2c1a/analytics?since=2026-08-01T00:00:00Z&window_days=14&goal_event=order.completed" \
  -H "X-API-Key: dv_live_sk_..."

Query parameters (all optional):

Parameter	Meaning
`since` / `until`	Bound the entry window (executions started within). Default: trailing 30 days ending now
`window_days`	Attribution window, in days after a contact exits the flow (1–365). Default: 7, or the goal’s configured window
`goal_event`	Override: count this event name as the conversion
`goal_trait` (+ `goal_value`)	Override: count an identify call setting this trait (optionally to the value) as the conversion

The conversion goal is normally configured on the flow itself as definition.conversionGoal (set it via PUT /flows/:id), either { "type": "event", "event": "order.completed", "windowDays": 7 } or { "type": "trait", "trait": "plan", "value": "pro", "windowDays": 7 }. The query params above override it for an ad-hoc funnel. A contact converts when it fires the goal event (or has the trait set) within the window after its execution reaches a terminal state.

{
  "data": {
    "flow_id": "flw_9f2c1a",
    "since": "2026-08-01T00:00:00Z",
    "until": "2026-09-02T00:00:00Z",
    "window_days": 14,
    "goal": { "type": "event", "event": "order.completed" },
    "entered": 1204,
    "completed": 1120,
    "converted": 388,
    "completion_rate": 0.9302,
    "conversion_rate": 0.3223,
    "funnel": [
      {
        "node_id": "send_welcome",
        "node_type": "sendSms",
        "label": "Welcome SMS",
        "reached": 1204,
        "dropped_off": 0,
        "step_conversion_rate": null,
        "overall_conversion_rate": 1
      },
      {
        "node_id": "wait_1d",
        "node_type": "delay",
        "label": null,
        "reached": 1190,
        "dropped_off": 14,
        "step_conversion_rate": 0.9884,
        "overall_conversion_rate": 0.9884
      }
    ]
  }
}

Per funnel step: reached is the number of executions that traversed the node, dropped_off the loss versus the previous step, step_conversion_rate is versus the previous step (null at the entry step), and overall_conversion_rate is versus the funnel entry. All counting is a read-side aggregation over the recorded executions — the executions log itself is untouched.

A/B Test Results

GET /flows/:id/ab-results rolls up every abTest (or experiment) node in the flow: per-variant assigned, completed, and converted counts with rates, plus the leading variant. It accepts the same since/until/window_days/goal-override parameters as /analytics.

curl -X GET "https://api.orbit.devotel.io/api/v1/flows/flw_9f2c1a/ab-results" \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "flow_id": "flw_9f2c1a",
    "since": "2026-08-03T00:00:00Z",
    "until": "2026-09-02T00:00:00Z",
    "window_days": 7,
    "goal": { "type": "event", "event": "order.completed" },
    "experiments": [
      {
        "node_id": "split_ab",
        "variants": [
          {
            "variant_id": "a",
            "variant_label": "Short copy",
            "assigned": 601,
            "completed": 570,
            "converted": 172,
            "completion_rate": 0.9484,
            "conversion_rate": 0.2862
          },
          {
            "variant_id": "b",
            "variant_label": "Long copy",
            "assigned": 603,
            "completed": 579,
            "converted": 195,
            "completion_rate": 0.9602,
            "conversion_rate": 0.3234
          }
        ],
        "winner_variant_id": "b"
      }
    ]
  }
}

The winner is the variant with the highest conversion rate when a goal is configured, or the highest completion rate when it is not. A tie at the top — as well as having no assignments yet — yields winner_variant_id: null, so the dashboard never declares a false winner.

How variant assignment works

Each abTest node pins its variant deterministically per contact: a hash of the contact’s key and the node id picks the bucket, so a contact that re-enters the flow re-derives the same variant — one sticky subject per variant, no stored assignment state. Weights come from each variant’s weight_pct (aliases weight / percentage are accepted); when no positive weights are set, the split is even. The executor records the assignment on the node’s own step output ({ ab_test: true, variant_id, variant_label } in the Executions step trace), and the ab-results rollup above reads assignments straight back off that trace — which matches the abTest row in the Edge Semantics table, where each variant id (a/b, or the variant’s handle id) routes over its own sourceHandle edge. Save-time validation (the GET /flows/:id/validate checks above) also runs on create/update, so a flow with fewer than two variants, or with explicit weights that do not sum to 100, is rejected before it ever runs. By default a variant is sticky for the contact. An abTest node with data.bandit_mode: true instead routes adaptively: it asks the real-time decisioning engine on each visit which variant currently leads (fed by the same assigned/converted counts ab-results reports) and routes toward that variant. Static validation of the variant shape still applies.

Conversation Flows for AI Agents

Classic Flows route CONTACTS through channel automations. AI agents get a second, in-conversation map: a conversation flow. Attach one under an agent’s config.conversation_flow and every turn routes between NAMED NODES (per-state instructions) instead of relying on a single static system prompt — keyword or regex edge conditions against the customer’s latest message decide which node’s instructions are active, validation rejects malformed graphs at save, and the route replays deterministically every turn over the conversation history. The feature lives in the Agents doc family — see Conversation flows for graph anatomy, conditions and fallbacks, the save-validation contract, versioning and A/B experiment pinning, deterministic replay, and worked billing/triage and escalation examples.

Next Steps

Flow Builder — the visual palette for triggers and core nodes
Flow execution model — execution states, async waits, branching, and version binding at runtime
Flow Executions — inspect per-node step traces and failures
Transport architecture — inbound vs outbound transport split
Webhooks — trigger flows from external events
AI Agents — add AI agents as flow nodes
Conversation flows — in-conversation routing for AI agents

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Visual workflow automation with Orbit Flows

Flows

What Are Flows?

Core Concepts

Use Cases

Trigger Catalog

Trigger payloads

Validate a Flow

Node Taxonomy

Action nodes

AI nodes

Logic nodes

Data nodes

Visual builder vs API-only

Edge Semantics

Where Flows Fire

Create a Flow via API

Node shape

Forecast a Flow Before Activation

Per-Flow Conversion Analytics

A/B Test Results

How variant assignment works

Conversation Flows for AI Agents

Next Steps

​Flows

​What Are Flows?

​Core Concepts

​Use Cases

​Trigger Catalog

​Trigger payloads

​Validate a Flow

​Node Taxonomy

​Action nodes

​AI nodes

​Logic nodes

​Data nodes

​Visual builder vs API-only

​Edge Semantics

​Where Flows Fire

​Create a Flow via API

​Node shape

​Forecast a Flow Before Activation

​Per-Flow Conversion Analytics

​A/B Test Results

​How variant assignment works

​Conversation Flows for AI Agents

​Next Steps

Flows

What Are Flows?

Core Concepts

Use Cases

Trigger Catalog

Trigger payloads

Validate a Flow

Node Taxonomy

Action nodes

AI nodes

Logic nodes

Data nodes

Visual builder vs API-only

Edge Semantics

Where Flows Fire

Create a Flow via API

Node shape

Forecast a Flow Before Activation

Per-Flow Conversion Analytics

A/B Test Results

How variant assignment works

Conversation Flows for AI Agents

Next Steps