Conversation Flow Design & Automation Guide

Build structured conversational experiences using workflows, branching logic, automation rules, and voice AI journeys.

Overview

Conversation flows let you model complex dialogues as a directed graph of nodes. Each node represents a step in the conversation — greeting the caller, asking a question, looking up data, or transferring the call. The agent follows the flow while still maintaining natural, AI-powered conversation.

  • Nodes define what the agent says or does at each step
  • Edges define transitions between nodes based on conditions
  • Variables collect and store caller responses for later use
  • Tool invocations can be triggered at any node
  • Flows are version-controlled alongside the agent

Conversation Flow JSON

{
  "id": "flow_abc123",
  "name": "Appointment Booking",
  "start_node": "greeting",
  "nodes": [
    {
      "id": "greeting",
      "type": "message",
      "content": "Hi! I can help you book an appointment. What date works best for you?",
      "transitions": [
        { "target": "collect_date", "condition": "always" }
      ]
    },
    {
      "id": "collect_date",
      "type": "input",
      "variable": "preferred_date",
      "validation": "date",
      "prompt": "What date would you prefer?",
      "transitions": [
        { "target": "collect_time", "condition": "input_valid" },
        { "target": "collect_date", "condition": "input_invalid" }
      ]
    },
    {
      "id": "collect_time",
      "type": "input",
      "variable": "preferred_time",
      "prompt": "Great! And what time works best?",
      "transitions": [
        { "target": "check_availability", "condition": "input_valid" }
      ]
    },
    {
      "id": "check_availability",
      "type": "tool_call",
      "tool": "api_check_slots",
      "params": {
        "date": "{{preferred_date}}",
        "time": "{{preferred_time}}"
      },
      "transitions": [
        { "target": "confirm_booking", "condition": "tool_result.available == true" },
        { "target": "suggest_alternative", "condition": "tool_result.available == false" }
      ]
    },
    {
      "id": "confirm_booking",
      "type": "message",
      "content": "Perfect! I've booked your appointment for {{preferred_date}} at {{preferred_time}}. You'll receive a confirmation shortly."
    }
  ]
}

Node Types

TypeDescription
messageThe agent speaks a fixed or templated message. Supports variable interpolation with {{variable_name}}.
inputCollects caller input and stores it in a named variable. Supports validation types: text, date, number, email, phone, yes_no.
tool_callInvokes a registered tool (MCP, API, or Connector) and stores the result. Transitions can branch based on the tool response.
transferTransfers the call to a human agent, another AI agent, or an external number.
conditionA decision node with no spoken output. Evaluates an expression and routes to different nodes based on the result.

Flow API

curl -X PUT https://api.voxentis.com/v1/agents/agt_9f2k4h1a/flow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Booking Flow", "start_node": "greeting", "nodes": [...] }'

Use the POST /agents/{id}/flow/generate endpoint to generate a conversation flow from a natural-language description using AI.