How Flows Work

Overview

A flow is a state machine that drives a conversation. At any point in time a conversation is in exactly one state. Each state defines what the chatbot says, what it expects from the user, and where the conversation goes next.

There are two flow types:

How a message travels through a flow

From the moment a user sends a message to the moment they receive a reply, the engine steps through this sequence:

States

A state is the basic unit of a flow. Each state has three parts:

• Message — what the chatbot sends when the conversation enters this state
• Actions — operations that run when the state is entered (API calls, agent turns, etc.)
• Transitions — named exits that define where the conversation goes next

In JSON, a flow is a map of state names to state objects:

{
  "greet_user": {
    "message": "Hi! What's your order number?",
    "actions": [],
    "transitions": {
      "default": "fetch_order"
    }
  },
  "fetch_order": {
    "message": "Looking that up for you...",
    "actions": [
      {
        "type": "API_CALL",
        "integration": "my_backend",
        "path": "/orders/{{variables.order_id}}",
        "save_to": "order",
        "success_transition": "show_status",
        "failure_transition": "order_error"
      }
    ]
  }
}{
  "greet_user": {
    "message": "Hi! What's your order number?",
    "actions": [],
    "transitions": {
      "default": "fetch_order"
    }
  },
  "fetch_order": {
    "message": "Looking that up for you...",
    "actions": [
      {
        "type": "API_CALL",
        "integration": "my_backend",
        "path": "/orders/{{variables.order_id}}",
        "save_to": "order",
        "success_transition": "show_status",
        "failure_transition": "order_error"
      }
    ]
  }
}

Transitions

Transitions are named paths from a state to another state. The engine follows a transition when:

• The user sends a message that matches a transition trigger
• An action completes and specifies a success_transition or failure_transition
• No other transition matches — the default transition is followed

Variables

Variables are key-value pairs that persist for the lifetime of a conversation. They accumulate as the user moves through states and are accessible everywhere using double-brace syntax: {{variables.key}}.

Built-in variables are set automatically:

Flow variables are set when:

• A user answers a question in a state that collects input
• An API_CALL completes and its response is saved via save_to

Use variables in messages, transition conditions, API paths, headers, and request bodies.

Action types

Actions run when the conversation engine enters a state. Multiple actions can be chained in a single state's actions array — they execute in order.