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

# Workflows Introduction

> Build multi-step outreach sequences that combine voice agent calls, WhatsApp messages, API calls, waits and retries, driven entirely through the Bolna API.

<Note>
  Workflows are in beta. The APIs documented here are stable to build against, but details may evolve before general availability — check the [changelog](/docs/changelog/august-2026) for updates.
</Note>

## What are Workflows?

A workflow is a graph of nodes connected by conditions. Where a [batch](/docs/guides/outbound/batch-calling) places one call per contact, a workflow orchestrates a whole sequence per contact: call them, branch on whether they picked up, retry twice with a 2-minute gap if they didn't, extract what they said if they did, push the result to your CRM, and follow up on WhatsApp — each contact walking the graph independently.

Typical uses:

* **Lead qualification** — call, score the conversation from extracted fields, route hot leads to an API and cold leads to a WhatsApp nurture message.
* **Collections and reminders** — call, capture a promise-to-pay date, record it via your API, schedule the follow-up.
* **Unreachable-contact handling** — retry ladders with configurable gaps, then a fallback channel.

***

## The object model

<CardGroup cols={2}>
  <Card title="Workflow" icon="diagram-project">
    The named container. Holds one mutable draft and any number of immutable published versions.
  </Card>

  <Card title="Draft and versions" icon="code-branch">
    You edit the draft, then publish it as a frozen version. Runs always execute published versions — publishing again never changes anything already running.
  </Card>

  <Card title="Campaign" icon="bullhorn">
    Runs one published version over a batch of uploaded contacts. Pins its version at creation time.
  </Card>

  <Card title="Execution" icon="route">
    One contact's journey through the graph — node attempts, matched cases, and a terminal outcome.
  </Card>
</CardGroup>

The lifecycle, end to end:

```
create workflow -> save draft -> validate -> publish (v1)
                                                |
                       +------------------------+------------------------+
                       |                                                 |
              run one contact                                    create campaign
       POST /workflows/{id}/run                     upload entries -> :start
                       |                                                 |
                       +----------------> executions <-------------------+
                                     poll until terminal
```

***

## Nodes at a glance

| Node type          | What it does                                                  | Branches on                           |
| ------------------ | ------------------------------------------------------------- | ------------------------------------- |
| `start`            | Entry point; declares the contact fields the workflow accepts | contact data (`entry.*`)              |
| `agent`            | Places a call with one of your Bolna agents                   | `call.status`, call insights          |
| `extraction`       | Exposes fields extracted from the preceding call              | `extraction.*`                        |
| `api`              | Calls an external HTTP endpoint                               | `response.status`, mapped values      |
| `aisensy_whatsapp` | Sends a WhatsApp template message via AiSensy                 | `whatsapp.status`                     |
| `time`             | Waits for a delay or until a timestamp                        | single exit, no branching             |
| `retry`            | Re-runs an earlier node on a schedule, up to N attempts       | evaluated once attempts are exhausted |
| `end`              | Terminates the execution with a label and an outcome          | terminal                              |

Each node routes onward through ordered **cases** — condition expressions over the execution's variables. See [Nodes](/docs/guides/workflows/nodes) for every node's configuration and [Conditions and variables](/docs/guides/workflows/conditions-and-variables) for the expression language.

***

## Authentication and conventions

All workflow endpoints live on the standard API host and authenticate with your Bolna API key:

```bash theme={"system"}
curl --location 'https://api.bolna.ai/workflows' \
--header 'Authorization: Bearer <api_key>'
```

Three conventions to know:

* **List endpoints paginate with `limit`/`offset`** and return `{items, total, limit, offset}`.
* **Errors carry a machine-readable code** in `detail.code` (for example `revision_conflict`, `duplicate_run`, `invalid_state`), with any extra context alongside it.
* **Action endpoints use a `:verb` suffix** — for example `POST /workflow-campaigns/{id}:start` — with an empty JSON body.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/guides/workflows/quickstart">
    Create, publish and run your first workflow with curl
  </Card>

  <Card title="Nodes" icon="circle-nodes" href="/docs/guides/workflows/nodes">
    Every node type with its configuration and examples
  </Card>

  <Card title="Conditions and variables" icon="code-branch" href="/docs/guides/workflows/conditions-and-variables">
    The expression language behind branching
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/docs/guides/workflows/campaigns">
    Run a workflow over thousands of contacts
  </Card>
</CardGroup>