Conversational Flows

Flows are deterministic conversation paths that guide users through structured interactions. While the AI agent handles free-form questions, flows ensure consistent data collection and multi-step processes.

What are Flows?

A Flow is a series of steps that execute in sequence when triggered. Each step can:

Send a message
Collect and validate user input
Branch based on conditions
Call webhook tools
Generate AI responses
Transfer to a human agent

[Trigger] → [Welcome] → [Collect Name] → [Collect Email] → [Confirm] → [End]

When to Use Flows

Scenario	Use Flow	Use Free-form LLM
Collecting required data (name, email, phone)	Yes	No
Compliance-required messaging	Yes	No
Appointment booking	Yes	Maybe
General Q&A	No	Yes
Product recommendations	No	Yes
Order status lookup	Maybe	Yes

Use flows when you need guaranteed outcomes. Use the LLM when you need flexibility.

Flow Triggers

Two trigger types run today:

Trigger Type	Description	Example
`keyword`	Message contains any of the words, case-insensitive substring match	”book”, “appointment”, “schedule”
`always`	Every inbound message that is not already inside a flow	Welcome/onboarding flow

always restarts once the flow completes, so the contact’s next message begins it again. It is not once per conversation.

intent and manual are accepted by the API and stored on the flow, and the matcher has no branch for either: a flow created with one is never triggered by anything and never says so. Use keyword or always.

Step Types

Every step has the same envelope. config is required, and its fields depend on type:

{
  "id": "<your-step-id>",
  "type": "message | collect | condition | tool | llm | transfer",
  "config": { },
  "nextStepId": "<id of the next step, or omit>"
}

That is the envelope, not a runnable step: config is empty because what goes in it depends on type. Each section below gives the real shape. Steps run in array order unless a step names nextStepId, or a condition sends the run elsewhere. A step with no nextStepId that is last in the array completes the flow.

Message Step

Send a fixed message. {{variables}} are replaced with what earlier steps collected.

{
  "id": "welcome",
  "type": "message",
  "config": {
    "text": "Welcome to Acme! How can I help you today?"
  },
  "nextStepId": "ask_email"
}

Collect Step

Ask for something and wait for the customer’s next message.

{
  "id": "ask_email",
  "type": "collect",
  "config": {
    "variable": "customer_email",
    "prompt": "What's your email address?",
    "validation": { "type": "email" },
    "errorMessage": "That does not look like an email address. Try again."
  },
  "nextStepId": "ask_size"
}

errorMessage sits beside validation, not inside it. Validation types

`type`	Extra fields	Accepts
`text`	`minLength`, `maxLength`	any text
`email`		a valid address
`phone`		a valid phone number
`number`	`min`, `max`	numeric input
`date`		accepts anything, see below
`choice`	`options` (required)	one of `options`

date currently accepts whatever the contact typed, including tomorrow and asdf, and minDate / maxDate are not read. Validate a date in your own handler, or constrain it with choice. choice is the reason to reach for a flow at all: the answer is constrained to your list, so what reaches your systems is one of a known set rather than whatever the customer typed.

{
  "id": "ask_size",
  "type": "collect",
  "config": {
    "variable": "size",
    "prompt": "How many people are on your team? Reply 1-10, 11-50, 51-200, or 200+.",
    "validation": { "type": "choice", "options": ["1-10", "11-50", "51-200", "200+"] },
    "errorMessage": "Please pick one of: 1-10, 11-50, 51-200, 200+."
  },
  "nextStepId": "route"
}

Condition Step

Branch. if is interpolated first, then compared, so "{{budget}} > 10000" becomes "25000 > 10000".

{
  "id": "route",
  "type": "condition",
  "config": {
    "conditions": [
      { "if": "{{size}} == 200+", "goto": "enterprise_path" }
    ],
    "defaultGoto": "standard_path"
  }
}

Supported operators are ==, !=, > and <. There is no AND, no OR and no parentheses. For anything more, chain several condition steps or move the decision into a tool. defaultGoto runs when no condition matches. Without it, and with nothing matching, the flow completes.

Tool Step

Call one of the agent’s tools.

{
  "id": "save_lead",
  "type": "tool",
  "config": {
    "toolName": "create_lead",
    "params": {
      "email": "{{customer_email}}",
      "size": "{{size}}",
      "source": "whatsapp"
    },
    "storeResultAs": "lead"
  },
  "nextStepId": "confirm"
}

Use config.toolName. config.toolId is the original spelling and still works: either field is accepted, and either one may hold the tool’s name or its id.A step pointing at a tool the agent does not have used to reply Tool "tool_9f2a..." not found to the customer as an ordinary message. It now ends the session and logs the misconfiguration instead, so the plain agent takes the conversation from the next message.The session ends as abandoned, not completed: the flow never reached the end you designed. Check that status if your completion numbers look better than the conversations do.

params values wrapped in {{ }} are replaced with collected data; anything else is passed through literally. (action appears in older examples and is accepted, but nothing reads it, so it is left out here.) params may be omitted for a tool that takes none. The tool must already exist on the agent before the flow runs.

LLM Step

Let the model answer, inside the flow.

{
  "id": "suggest",
  "type": "llm",
  "config": {
    "systemPrompt": "Suggest three products for a team of {{size}}. Be brief.",
    "collectVariable": "recommendations"
  },
  "nextStepId": "confirm"
}

Transfer Step

End the flow and hand off to a human.

{
  "id": "escalate",
  "type": "transfer",
  "config": {
    "message": "I'm connecting you with a specialist. Please hold."
  }
}

This sends message, marks the session transferred, and silences the agent for that contact. Their next messages are stored and appear in your inbox, and the agent does not answer them: a contact who asked for a person is not talked over by the bot while they wait. The agent takes the thread back as soon as someone answers. Any outbound message you send to that contact, from the inbox or the API, ends the handoff. There is no button to press and no state to clean up.

Nobody is notified for you. There is no queue and no assignment: the conversation waits in the inbox until a person opens it. If your team does not watch the inbox, put a tool step before the transfer and notify yourself from your own systems.notifyWebhook and reason are accepted on the config and never read.

Variables

{{name}} in any string is replaced with what an earlier step collected. A variable that was never collected renders as the literal {{name}} in the message the customer receives, so check that every one is populated before it is used. Variables come from three places:

Step type	Field that creates the variable
`collect`	`config.variable`
`tool`	`config.storeResultAs`
`llm`	`config.collectVariable`

Via Dashboard

Navigate to Flows

Go to Senders > select your sender > Agent tab > Flows section.

Create New Flow

Click Create Flow and enter:

Name: A descriptive name (e.g., “Lead Capture Flow”)
Description: What this flow does
Trigger: How the flow is activated

Add Steps

Use the visual flow builder to add steps:

Click Add Step
Select the step type
Configure the step parameters
Connect steps by dragging between nodes

Configure Triggers

Set up how the flow is triggered:

For keyword triggers, enter the words that activate the flow
For intent triggers, describe the intent in natural language
For always, the flow runs on every new conversation

Test the Flow

Use the Test button to simulate a conversation and verify each step works correctly.

Activate Flow

Toggle the flow to Active to enable it for incoming messages.

Via API

Create Flow

import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env["ZAVUDEV_API_KEY"] });

const flow = await zavu.senders.agent.flows.create("sender_abc123", {
  name: "Lead Capture",
  description: "Collect lead information from new contacts",
  trigger: {
    type: "keyword",
    keywords: ["interested", "info", "learn more"],
  },
  steps: [
    {
      id: "welcome",
      type: "message",
      config: { text: "Great! I'd love to help. Let me collect some information." },
      nextStepId: "get_name",
    },
    {
      id: "get_name",
      type: "collect",
      config: { variable: "customer_name", prompt: "What's your name?" },
      nextStepId: "get_email",
    },
    {
      id: "get_email",
      type: "collect",
      config: {
        variable: "customer_email",
        prompt: "What's your email address?",
        validation: { type: "email" },
        errorMessage: "That does not look like an email address. Try again.",
      },
      nextStepId: "confirm",
    },
    {
      id: "confirm",
      type: "message",
      config: {
        text: "Thanks {{customer_name}}! Our team will contact you at {{customer_email}} within 24 hours.",
      },
    },
  ],
});

console.log("Flow created:", flow.id);

import os
from zavudev import Zavudev

zavu = Zavudev(api_key=os.environ.get("ZAVUDEV_API_KEY"))

flow = zavu.senders.agent.flows.create(
    "sender_abc123",
    name="Lead Capture",
    description="Collect lead information from new contacts",
    trigger={"type": "keyword", "keywords": ["interested", "info", "learn more"]},
    steps=[
        {
            "id": "welcome",
            "type": "message",
            "config": {"text": "Great! I'd love to help. Let me collect some information."},
            "nextStepId": "get_name",
        },
        {
            "id": "get_name",
            "type": "collect",
            "config": {"variable": "customer_name", "prompt": "What's your name?"},
            "nextStepId": "get_email",
        },
        {
            "id": "get_email",
            "type": "collect",
            "config": {
                "variable": "customer_email",
                "prompt": "What's your email address?",
                "validation": {"type": "email"},
                "errorMessage": "That does not look like an email address. Try again.",
            },
            "nextStepId": "confirm",
        },
        {
            "id": "confirm",
            "type": "message",
            "config": {
                "text": "Thanks {{customer_name}}! Our team will contact you at {{customer_email}} within 24 hours."
            },
        },
    ],
)

print(f"Flow created: {flow.id}")

require "zavudev"

client = Zavudev::Client.new(api_key: ENV["ZAVUDEV_API_KEY"])

flow = client.senders.agent.flows.create("sender_abc123",
  name: "Lead Capture",
  description: "Collect lead information from new contacts",
  trigger: { type: "keyword", keywords: ["interested", "info", "learn more"] },
  steps: [
    {
      id: "welcome",
      type: "message",
      config: { text: "Great! I'd love to help. Let me collect some information." },
      nextStepId: "get_name"
    },
    {
      id: "get_name",
      type: "collect",
      config: { variable: "customer_name", prompt: "What's your name?" },
      nextStepId: "get_email"
    },
    {
      id: "get_email",
      type: "collect",
      config: {
        variable: "customer_email",
        prompt: "What's your email address?",
        validation: { type: "email" },
        errorMessage: "That does not look like an email address. Try again."
      },
      nextStepId: "confirm"
    },
    {
      id: "confirm",
      type: "message",
      config: {
        text: "Thanks {{customer_name}}! Our team will contact you at {{customer_email}} within 24 hours."
      }
    }
  ]
)

puts "Flow created: #{flow.id}"

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

func main() {
	client := zavudev.NewClient(option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")))

	flow, err := client.Senders.Agent.Flows.New(context.TODO(), "sender_abc123", zavudev.FlowNewParams{
		Name:        zavudev.F("Lead Capture"),
		Description: zavudev.F("Collect lead information from new contacts"),
		Trigger: zavudev.F(zavudev.FlowTriggerParam{
			Type:     zavudev.F(zavudev.FlowTriggerTypeKeyword),
			Keywords: zavudev.F([]string{"interested", "info", "learn more"}),
		}),
		Steps: zavudev.F([]zavudev.FlowStepParam{
			{
				ID:     zavudev.F("welcome"),
				Type:   zavudev.F(zavudev.FlowStepTypeMessage),
				Config: zavudev.F(map[string]interface{}{"text": "Great! I'd love to help. Let me collect some information."}),
				NextStepID: zavudev.F("get_name"),
			},
			{
				ID:   zavudev.F("get_name"),
				Type: zavudev.F(zavudev.FlowStepTypeCollect),
				Config: zavudev.F(map[string]interface{}{
					"variable": "customer_name",
					"prompt":   "What's your name?",
				}),
				NextStepID: zavudev.F("get_email"),
			},
			{
				ID:   zavudev.F("get_email"),
				Type: zavudev.F(zavudev.FlowStepTypeCollect),
				Config: zavudev.F(map[string]interface{}{
					"variable":     "customer_email",
					"prompt":       "What's your email address?",
					"validation":   map[string]interface{}{"type": "email"},
					"errorMessage": "That does not look like an email address. Try again.",
				}),
				NextStepID: zavudev.F("confirm"),
			},
			{
				ID:     zavudev.F("confirm"),
				Type:   zavudev.F(zavudev.FlowStepTypeMessage),
				Config: zavudev.F(map[string]interface{}{"text": "Thanks {{customer_name}}! Our team will contact you at {{customer_email}} within 24 hours."}),
			},
		}),
	})
	if err != nil {
		panic(err)
	}

	fmt.Printf("Flow created: %s\n", flow.ID)
}

curl -X POST https://api.zavu.dev/v1/senders/sender_abc123/agent/flows \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Capture",
    "description": "Collect lead information from new contacts",
    "trigger": { "type": "keyword", "keywords": ["interested", "info", "learn more"] },
    "steps": [
      {
        "id": "welcome",
        "type": "message",
        "config": { "text": "Great! I would love to help. Let me collect some information." },
        "nextStepId": "get_name"
      },
      {
        "id": "get_name",
        "type": "collect",
        "config": { "variable": "customer_name", "prompt": "What is your name?" },
        "nextStepId": "get_email"
      },
      {
        "id": "get_email",
        "type": "collect",
        "config": {
          "variable": "customer_email",
          "prompt": "What is your email address?",
          "validation": { "type": "email" },
          "errorMessage": "That does not look like an email address. Try again."
        },
        "nextStepId": "confirm"
      },
      {
        "id": "confirm",
        "type": "message",
        "config": {
          "text": "Thanks {{customer_name}}! Our team will contact you at {{customer_email}} within 24 hours."
        }
      }
    ]
  }'

List Flows

const flows = await zavu.senders.agent.flows.list("sender_abc123");

for (const flow of flows.items) {
  console.log(`${flow.name} (${flow.id}) - ${flow.enabled ? "Active" : "Inactive"}`);
}

flows = zavu.senders.agent.flows.list("sender_abc123")

for flow in flows.items:
    status = "Active" if flow.enabled else "Inactive"
    print(f"{flow.name} ({flow.id}) - {status}")

flows = client.senders.agent.flows.list("sender_abc123")

flows.items.each do |flow|
  status = flow.enabled ? "Active" : "Inactive"
  puts "#{flow.name} (#{flow.id}) - #{status}"
end

flows, _ := client.Senders.Agent.Flows.List(context.TODO(), "sender_abc123", zavudev.FlowListParams{})

for _, flow := range flows.Items {
	status := "Inactive"
	if flow.Enabled {
		status = "Active"
	}
	fmt.Printf("%s (%s) - %s\n", flow.Name, flow.ID, status)
}

$flows = $client->senders->agent->flows->list('sender_abc123');

foreach ($flows->items as $flow) {
    $status = $flow->enabled ? 'Active' : 'Inactive';
    echo "{$flow->name} ({$flow->id}) - {$status}\n";
}

curl https://api.zavu.dev/v1/senders/sender_abc123/agent/flows \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Update Flow

const flow = await zavu.senders.agent.flows.update(
  "flow_xyz789",
  {
    senderId: "sender_abc123",
    name: "Updated Lead Capture",
    enabled: true,
  }
);

flow = zavu.senders.agent.flows.update(
    "sender_abc123",
    "flow_xyz789",
    name="Updated Lead Capture",
    enabled=True,
)

flow = client.senders.agent.flows.update("flow_xyz789",
  sender_id: "sender_abc123",
  name: "Updated Lead Capture",
  enabled: true
)

flow, _ := client.Senders.Agent.Flows.Update(context.TODO(), "flow_xyz789", zavudev.FlowUpdateParams{
	SenderID: zavudev.String("sender_abc123"),
	Name:     zavudev.String("Updated Lead Capture"),
	Enabled:  zavudev.Bool(true),
})

$flow = $client->senders->agent->flows->update('sender_abc123', 'flow_xyz789', [
    'name' => 'Updated Lead Capture',
    'enabled' => true,
]);

curl -X PATCH https://api.zavu.dev/v1/senders/sender_abc123/agent/flows/flow_xyz789 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Lead Capture", "enabled": true}'

Example Flows

Lead Capture Flow

Qualify an inbound lead into three known fields before anyone reads the thread.

{
  "name": "Lead Capture",
  "trigger": { "type": "keyword", "keywords": ["pricing", "demo", "info"] },
  "enabled": true,
  "priority": 10,
  "steps": [
    {
      "id": "intro",
      "type": "message",
      "config": { "text": "Thanks for your interest! Let me get some details." },
      "nextStepId": "get_name"
    },
    {
      "id": "get_name",
      "type": "collect",
      "config": { "variable": "name", "prompt": "What's your name?" },
      "nextStepId": "get_email"
    },
    {
      "id": "get_email",
      "type": "collect",
      "config": {
        "variable": "email",
        "prompt": "What's your email?",
        "validation": { "type": "email" },
        "errorMessage": "That does not look like an email address. Try again."
      },
      "nextStepId": "get_size"
    },
    {
      "id": "get_size",
      "type": "collect",
      "config": {
        "variable": "size",
        "prompt": "How many employees? Reply 1-10, 11-50, 51-200 or 200+.",
        "validation": { "type": "choice", "options": ["1-10", "11-50", "51-200", "200+"] },
        "errorMessage": "Please reply with 1-10, 11-50, 51-200 or 200+."
      },
      "nextStepId": "save_lead"
    },
    {
      "id": "save_lead",
      "type": "tool",
      "config": {
        "toolName": "create_lead",
            "params": { "name": "{{name}}", "email": "{{email}}", "companySize": "{{size}}" }
      },
      "nextStepId": "confirm"
    },
    {
      "id": "confirm",
      "type": "message",
      "config": { "text": "Thanks {{name}}! A team member will reach out within 24 hours." }
    }
  ]
}

The choice step is what makes this worth a flow: size reaching your CRM is always one of four values, not whatever the customer typed.

Appointment Booking Flow

{
  "name": "Appointment Booking",
  "trigger": { "type": "keyword", "keywords": ["book", "appointment", "schedule"] },
  "enabled": true,
  "priority": 10,
  "steps": [
    {
      "id": "intro",
      "type": "message",
      "config": { "text": "I'd be happy to help you book an appointment!" },
      "nextStepId": "get_service"
    },
    {
      "id": "get_service",
      "type": "collect",
      "config": {
        "variable": "service_type",
        "prompt": "What type of appointment? Reply consultation, follow-up or review.",
        "validation": { "type": "choice", "options": ["consultation", "follow-up", "review"] },
        "errorMessage": "Please reply with consultation, follow-up or review."
      },
      "nextStepId": "get_date"
    },
    {
      "id": "get_date",
      "type": "collect",
      "config": {
        "variable": "preferred_date",
        "prompt": "What date works best?",
        "validation": { "type": "date" }
      },
      "nextStepId": "check_slots"
    },
    {
      "id": "check_slots",
      "type": "tool",
      "config": {
        "toolName": "get_available_slots",
            "params": { "date": "{{preferred_date}}", "service": "{{service_type}}" },
        "storeResultAs": "slots"
      },
      "nextStepId": "show_slots"
    },
    {
      "id": "show_slots",
      "type": "message",
      "config": { "text": "Available times on {{preferred_date}}: {{slots}}" },
      "nextStepId": "get_time"
    },
    {
      "id": "get_time",
      "type": "collect",
      "config": { "variable": "selected_time", "prompt": "Which time works for you?" },
      "nextStepId": "book"
    },
    {
      "id": "book",
      "type": "tool",
      "config": {
        "toolName": "create_appointment",
            "params": {
          "service": "{{service_type}}",
          "date": "{{preferred_date}}",
          "time": "{{selected_time}}"
        }
      },
      "nextStepId": "confirm"
    },
    {
      "id": "confirm",
      "type": "message",
      "config": {
        "text": "Your {{service_type}} appointment is booked for {{preferred_date}} at {{selected_time}}. See you then!"
      }
    }
  ]
}

Both toolName values above must match tools that already exist: create_lead, get_available_slots and create_appointment must already exist on the agent.

Flow Sessions

When a user enters a flow, a session is created to track their progress. Sessions store:

Current step
Collected variables
Timestamps
Channel information

Sessions do not expire. A contact who stops answering halfway keeps an open session, and their next message resumes that flow at the step they left, weeks later, with the variables they had. It is not restarted, and there is no timeout.Plan for it: give a long flow a way out, and do not assume a collect step is answered by the message that follows it in the same hour. A flow that ends in a transfer or completes cleanly closes its session, which is the reliable way to stop one.There is also no API for reading sessions. The status is visible in the dashboard.

Best Practices

Keep Flows Short

Aim for 5-7 steps maximum. Long flows have higher abandonment rates.

Validate Early

Validate critical inputs (email, phone) immediately after collection.

Provide Exit Points

Let users say “stop” or “cancel” to exit the flow at any time.

Use Variables

Reference collected data in messages to personalize the experience.

Next Steps

Add Tools

Enable your flows to execute actions via webhooks

Knowledge Base

Let your agent answer questions from documents

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Conversational Flows