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

# Flows Overview

> Visual workflow builder for communication automation

# 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

## Create a Flow via API

```bash theme={null}
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), and an optional `sourceHandle` (`"yes"`/`"no"` for a
`condition` node, `"error"` for an error path).

Messaging nodes are per-channel — the channel is part of the node type,
so there is no separate `channel` field:

| Node type                                                                                                                                           | Action                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `sendSms`, `sendWhatsapp`, `sendEmail`, `sendRcs`, `sendViber`, `sendLine`, `sendTelegram`, `sendInstagram`, `sendMessenger`, `sendPush`, `sendFax` | Send a message on that channel — `data.to` and `data.body`                             |
| `makeCall`                                                                                                                                          | Place an outbound voice call — `data.to`, `data.callerId`                              |
| `delay`                                                                                                                                             | Pause the flow — `data.amount` and `data.unit` (`seconds`, `minutes`, `hours`, `days`) |
| `condition`                                                                                                                                         | Branch on a field — `data.field`, `data.operator`, `data.value`                        |
| `webhook`                                                                                                                                           | Call an external API — `data.url`, `data.method`                                       |
| `aiAgent`                                                                                                                                           | Run an AI agent — `data.agent_id`                                                      |

An unrecognized node type is skipped at runtime, so a node sends nothing
unless its `type` matches one the executor implements.

## Next Steps

* [Flow Builder](/flows/builder) — learn how to use the visual builder
* [Webhooks](/webhooks/overview) — trigger flows from external events
* [AI Agents](/agents/overview) — add AI agents as flow nodes