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

# Transitions

> Control conversation flow with natural language, equations, DTMF, and auto transitions

Transitions define when and how the conversation moves from one node to another. Each node can have multiple transitions; the first matching transition fires.

## Transition Types

| Type         | Evaluation   | Use Case                                                 |
| ------------ | ------------ | -------------------------------------------------------- |
| **Prompt**   | LLM-based    | Natural language condition — intent detection, sentiment |
| **Equation** | Rule-based   | Variable comparisons, thresholds                         |
| **DTMF**     | Keypad input | IVR menus, quick selection                               |
| **Auto**     | Automatic    | Auto-advance when node completes                         |

***

## Availability by Node Type

Not all transition types are available on every node. Some nodes have fixed transitions that cannot be added, removed, or edited.

| Node Type                           | Available Transitions                                     |
| ----------------------------------- | --------------------------------------------------------- |
| **Conversation**                    | Prompt, DTMF, Auto                                        |
| **Start** (conversation mode)       | Prompt, DTMF                                              |
| **Start** (tool mode)               | Fixed: "On Success" and "On Failure" (cannot be modified) |
| **Router**                          | Equation only, plus a fixed "Else" fallback               |
| **Tool / Web Tool**                 | Fixed: "On Success" and "On Failure" (cannot be modified) |
| **Transfer Call / Transfer Agent**  | Fixed: "On Failure" only (cannot be modified)             |
| **Set Variables / Change Settings** | Fixed: auto-transition (cannot be modified)               |
| **End Call**                        | None (terminal node)                                      |

<Note>
  **Fixed transitions** on Tool, Web Tool, Transfer, and Start (tool mode) nodes are pre-configured and cannot be added, removed, or edited by the user.
</Note>

***

## Prompt Transitions (Natural Language)

The LLM evaluates whether the condition is met based on the caller's input and conversation context.

### Configuration

```typescript theme={null}
{
  type: 'natural_language',
  prompt: string,       // Condition description (required)
  description?: string
}
```

### Examples

```yaml theme={null}
Prompt: "The user wants to speak with a human agent"
→ Target: Transfer_to_Agent

Prompt: "The user is asking about billing or payment issues"
→ Target: Billing_Department

Prompt: "The user agrees or says yes"
→ Target: Confirm_Path

Prompt: "The user declines or says no"
→ Target: Alternative_Path
```

Write conditions that describe user intent, not exact phrases. "The user wants to speak with a human" matches "get me an agent", "transfer me", "I need a person", etc.

***

## Equation Transitions (Structured)

Equation transitions evaluate variable conditions using rule-based logic — no LLM involved. They are only available on **Router** nodes.

### Configuration

```typescript theme={null}
{
  type: 'structured_equation',
  logic: 'all' | 'any',    // AND or OR
  conditions: Array<{
    variable: string,
    operator: Operator,
    value: string | number | boolean,
    description?: string
  }>,
  description?: string
}
```

### Operators

| Operator                | Symbol | Description                   |
| ----------------------- | ------ | ----------------------------- |
| `equals`                | `=`    | Exact match                   |
| `not_equals`            | `≠`    | Not equal                     |
| `greater_than`          | `>`    | Numeric greater than          |
| `less_than`             | `<`    | Numeric less than             |
| `greater_than_or_equal` | `≥`    | Numeric greater than or equal |
| `less_than_or_equal`    | `≤`    | Numeric less than or equal    |
| `contains`              | `∋`    | String contains substring     |
| `not_contains`          | `∌`    | String does not contain       |
| `exists`                | `∃`    | Variable has any value        |
| `not_exists`            | `∄`    | Variable is null/undefined    |
| `regex`                 | `(.*)` | Regular expression match      |

<Note>
  When using numeric operators (`>`, `≥`, `<`, `≤`), the variable must be a number or convertible to a number. Hamsa handles type coercion automatically — a string `"25"` compared to number `21` with `greater_than` evaluates correctly.
</Note>

### Examples

**Single condition:**

```yaml theme={null}
Variable: account_status
Operator: equals
Value: 'active'
→ Target: Active_Account_Path
```

**AND logic (all conditions must pass):**

```yaml theme={null}
Logic: all
Conditions:
  - account_balance > 1000
  - account_type equals "premium"
→ Target: VIP_Path
```

**OR logic (any condition passes):**

```yaml theme={null}
Logic: any
Conditions:
  - support_tier equals "platinum"
  - is_enterprise equals true
→ Target: Priority_Support
```

**Existence check:**

```yaml theme={null}
Variable: customer_id
Operator: exists
→ Target: Known_Customer_Path
```

### Router "Else" Fallback

Every router node has a fixed "Else" transition that acts as the default fallback when no equation conditions match. This transition cannot be removed or edited — it is always present and always evaluated last.

```yaml theme={null}
Router Node: "Account Router"
Transitions:
  - Equation: account_type equals "premium" → Premium_Flow
  - Equation: account_type equals "standard" → Standard_Flow
  - Else → Basic_Flow    # Fixed, cannot be removed
```

***

## DTMF Transitions

DTMF transitions fire when the caller presses a specific keypad key. They are available on **Conversation** and **Start** nodes.

→ See [DTMF Features](./dtmf) for full documentation on all DTMF capabilities.

### Configuration

```typescript theme={null}
{
  type: 'dtmf',
  key: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '*' | '#',
  description?: string
}
```

### Example

```yaml theme={null}
Conversation Node: "Main Menu"
Message: "Press 1 for Sales, Press 2 for Support, Press 3 for Billing"
Transitions:
  - DTMF: key=1 → Sales_Department
  - DTMF: key=2 → Support_Department
  - DTMF: key=3 → Billing_Department
```

### DTMF Capture Restrictions

When [DTMF input capture](./dtmf) is enabled on a node, DTMF transitions are restricted:

* Only the termination keys (`*` and `#`) can be used as transition keys — number keys (0–9) are disabled.
* A maximum of 2 DTMF transitions are allowed (one for each termination key).
* Any existing number-key transitions are automatically disabled.
* Keys already used for [global node](./global-nodes) triggers are also unavailable.

***

## Auto Transitions

Auto transitions advance to the next node automatically when the current node completes. They are only available on **Conversation** nodes.

### Configuration

```typescript theme={null}
{
  type: 'auto',
  description: string   // Defaults to "Auto-advance"
}
```

### Example

```yaml theme={null}
Conversation Node: "Greeting"
Message: "Welcome! Let me transfer you to the right department."
Transitions:
  - Auto → Route_Department
```

### Behavior

Adding an auto transition has significant effects on the node:

* **All existing transitions are disabled** — they are kept but marked inactive.
* **All existing connection edges are deleted** — only the auto-transition connection remains.
* **You cannot have both auto and manual transitions** on the same node.

When you later remove the auto transition to switch back to manual transitions, previously disabled transitions are re-enabled, but you will need to manually reconnect the edges.

***

## Return to Source

When a node has **Return to Source** enabled, all transitions on that node are disabled. The node returns control to whichever node called it instead of following any transition path. Toggle off "Return to Source" to re-enable transitions.

***

## Advanced Patterns

### Combining prompt and DTMF

```yaml theme={null}
Conversation Node: "Support Menu"
Message: "Describe your issue, or press 0 for an agent"
Transitions:
  - DTMF: key=0 → Transfer_Agent
  - Prompt: "urgent issue" → Urgent
  - Prompt: "billing" → Billing
```

### Time-based routing

```yaml theme={null}
Router Node: "Hours Check"
Transitions:
  - Equation: Logic=all
    Conditions:
      - current_hour >= 9
      - current_hour < 17
    Target: Business_Hours_Flow
  - Else → After_Hours_Flow
```

***

## Validation

The flow builder validates transitions before deployment:

* All transitions have non-empty conditions (prompts, equation conditions, DTMF keys)
* DTMF keys are valid (0–9, \*, #)
* DTMF termination keys do not conflict between input capture and transitions
* Numeric operators must have numeric values or variable references

***

## Transition Schema

```typescript theme={null}
interface Transition {
  id: string;
  name?: string;
  condition:
    | NaturalLanguageCondition
    | StructuredEquationCondition
    | DTMFCondition
    | AutoCondition
    | AlwaysCondition;
  targetNodeId: string;
  isEnabled: boolean;
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Global Nodes" href="./global-nodes">
    Nodes reachable from anywhere in the flow
  </Card>

  <Card title="DTMF Features" href="./dtmf">
    Full keypad interaction documentation
  </Card>

  <Card title="Variables" href="/agents/variables/introduction">
    Variables used in equation conditions
  </Card>

  <Card title="Router Node" href="./nodes/router-node">
    Pure routing without conversation
  </Card>
</CardGroup>