# Flows

A flow is a structured conversation script that guides the AI through a fixed sequence of steps. Use flows when you need guaranteed, consistent behaviour — onboarding sequences, lead capture forms, appointment booking — where the AI should follow a defined path rather than freeform conversation.

## How flows work

A flow defines a series of **steps**. At each step, the AI delivers a message (or asks a question) and waits for the user's response before moving to the next step. You can branch based on user input.

When a flow is attached to a chatbot:
- The chatbot enters the flow when the trigger condition is met (e.g. the conversation starts, or the user says a specific phrase).
- The flow runs until it completes or the user exits it.
- After the flow ends, the chatbot returns to normal freeform conversation.

## Creating a flow

### Via the dashboard

Go to **Flows > New flow**. Use the visual flow builder to add steps, set messages, and define branches.

### Via AI generation

Describe what you want the flow to do and Elaras generates a draft:

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/flows/generate" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Collect the user'\''s name, email, and the nature of their support request, then confirm a callback time."
  }'
```

The response includes a complete flow definition you can review and edit before saving.

### Via the API (direct)

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/flows" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead capture",
    "steps": [
      {
        "id": "greeting",
        "message": "Hi! Before I help you, could I grab your name?",
        "collect": "name",
        "next": "email"
      },
      {
        "id": "email",
        "message": "Thanks {{name}}! And your email address?",
        "collect": "email",
        "next": "done"
      },
      {
        "id": "done",
        "message": "Perfect — you'\''re all set. How can I help today?"
      }
    ]
  }'
```

## Updating a flow

```bash
curl -X PUT "https://api.elaras.ai/api/developer/v1/flows/{flow_id}" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead capture v2",
    "steps": [...]
  }'
```

## Attaching a flow to a chatbot

A flow must be attached to a chatbot before it runs. You can attach one or more flows; the trigger conditions determine which flow activates.

```bash
curl -X POST "https://api.elaras.ai/api/developer/v1/chatbots/{chatbot_id}/flows" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "flw_abc123",
    "trigger": "conversation_start"
  }'
```

**Trigger options:**

| Trigger | When the flow starts |
|---|---|
| `conversation_start` | The user sends their first message |
| `keyword` | The user's message matches a keyword or phrase you specify |
| `manual` | Triggered programmatically via the SDK |

## Listing flows

```bash
curl "https://api.elaras.ai/api/developer/v1/flows" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

## Deleting a flow

```bash
curl -X DELETE "https://api.elaras.ai/api/developer/v1/flows/{flow_id}" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

Deleting a flow detaches it from all chatbots automatically.

## Tips

- **Use flows for structured data collection.** Freeform conversation is great for Q&A, but flows are better when you need specific fields (name, email, date) reliably captured.
- **Keep flows short.** Long linear flows feel like form-filling. If you need more than 5–6 steps, consider breaking the intent into multiple shorter flows or using a skill to handle the data.
- **Combine flows and skills.** A flow can collect parameters that a skill then uses — for example, a booking flow that collects a date and time, followed by a `create_booking` skill call.