> ## 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: how a call moves to the next step

> Every transition type in a flow agent, which steps offer it, and exactly how the next step is chosen on a call: model choice, rules, keys and live variables.

Transitions are the ways out of a step. Each one says when the call should leave and, through its connection on the canvas, where it goes. This page explains every transition type and how the agent picks the next step during a call.

## How the next step is chosen

Who decides depends on the transition type:

| Type | Who decides | When it's checked |
| - | - | - |
| **Prompt** | The model, from what the caller said | When the model replies to the caller |
| **Equation** (Router only) | Fixed rules on variables | As soon as the call reaches the router |
| **Skip if** | Fixed rules on variables | As soon as the call reaches the step, before it speaks |
| **When a live variable matches** | Fixed rules on live variables | When the call arrives, and after each caller turn |
| **DTMF input** | The key the caller presses | On each key press |
| **Auto** | Nobody: the step moves on | Right after the step's message has played |
| **After user replies** | Nobody: the step moves on | As soon as the caller finishes speaking |
| **Return to source** (Conversation only) | The model, from what the caller said | When the model replies to the caller |
| Fixed (**On Success**, **On Failure**, **Else**, **Auto-advance**) | The step's own result | When the step finishes its work |

Rules, keys and fixed transitions always behave the same way for the same values. Prompt transitions depend on the model's reading of the conversation, so describe them well. See [Design tips](https://docs.tryhamsa.com/agents/flow/design-tips.md).

A transition only works once it's connected to a step on the canvas. Turned off or unconnected transitions are ignored on calls.

## Which steps offer which types

Add a transition on the step card: click **Add** ("Add new transition") and pick a type. Then click the transition on the card to set it up in the step's settings panel. Every step with transitions lists them in its **Transitions** section, and each row there opens that transition's settings too.

![The Add menu on the Start step card, offering Prompt, When a live variable matches, DTMF input and After user replies](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/flow/add-transition-menu-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=3dfde32c2e8cc40cca6c9fb3669f7a97)

| Step | Fixed transitions | Types you can add |
| - | - | - |
| Start (conversation) | none | **Prompt**, **When a live variable matches**, **DTMF input**, **After user replies** |
| Start (tool) | **On Success**, **On Failure** | none |
| Conversation | none | **Prompt**, **When a live variable matches**, **DTMF input**, **Skip if**, **Auto**, **After user replies**, **Return to source** |
| Router | **Else** (always last, can't be removed) | **Equation**, **Skip if** |
| Tool, Web tool | **On Success**, **On Failure** | **Skip if** |
| Transfer call, Transfer to agent | **On Failure** | **Skip if** |
| Set local variables, Change agent settings | **Auto-advance** | **Skip if** |
| End call | none | none |

## Prompt

A **Prompt** transition ("Natural language condition") is taken when the model decides that what the caller said fits it.

**1. Add it**

On a Conversation or Start step, click **Add** and choose **Prompt**.

**2. Describe when to take it**

Click the transition on the card (or its row under the step's **Transitions**) to open its settings, and fill in **When to take this path**: "Describe what the caller says or does that leads here." For example: "The caller wants to change an existing booking."

![The settings of a Prompt transition: When to take this path filled in, Offer it only when reading Always offered, and the variables extracted on this path](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/prompt-transition-settings-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=52d80e72d4ff945e05a388153830d3d9)

**3. Optionally, limit when it's offered**

Under **Offer it only when**, add rules on variables. "Until these hold, the agent doesn't consider this path. They're checked again before each reply." With no rules it reads **Always offered**; with rules the card shows a **Conditioned** tag, and the step's **Transitions** list shows the rules, for example "Only when phone\_number ∃".

![The Transitions section of the Verify the order step: one Prompt transition Always offered, and one reading Only when phone\_number exists](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/step-transitions-list-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=ce539b3e4a67c06c22925b86ba7829d0)

**4. Connect it**

Drag from its handle to the next step.

### How the model picks a prompt transition

* Every prompt transition on the step the call is in is offered to the model as a possible move, described by its **When to take this path** text. Every [global step](https://docs.tryhamsa.com/agents/flow/global-steps.md) is offered too, described by its trigger condition.
* When the caller speaks, the model replies. If one of the offered moves fits, it takes that move instead of answering in place. If none fits, it answers and the call stays in the step.
* The transitions have no order: the model picks the one whose description fits best. Write descriptions that don't overlap.
* A step's opening line can't take a move. The call moves on only in reply to something the caller said, and at most one prompt move happens per caller turn.
* A transition with **Offer it only when** rules is hidden from the model while its rules don't hold. The rules are checked again before every reply.

### Variables collected on the way out

A Conversation step can have **Variable on node exit** variables (see [Extract values from the conversation](https://docs.tryhamsa.com/agents/variables/extracted-variables.md)). The model fills them in when it takes a prompt transition.

* A required variable must have a value before the model can take the transition. The model asks the caller for it first.
* A variable that already has a value is offered for update, not asked again.
* If a variable has **Check the value** rules and the value fails, the value isn't kept. If that leaves a required variable without a valid value, the move doesn't happen and the model asks the caller again.
* Per transition, **Extractions** in its settings lets you switch variables off for that path. Variables left off are not collected when the call takes it. The card sums it up as **Extracted on this path** and **Ignored on this path**.

## Equation (router conditions)

An **Equation** transition ("Rule-based condition") is how a [Router step](https://docs.tryhamsa.com/agents/flow/steps/router.md) decides. The router runs without the model and without speaking.

**1. Add a condition**

On a Router step, click **Add** and choose **Equation**. Under **Conditions**, pick a variable, an operator and a value. The value can be fixed text, a number, or another `{{variable}}`.

**2. Combine conditions**

Click **Add condition** for more, and choose **All** or **Any** "of the following conditions match".

![A router path with two conditions joined by All: order\_status equals shipped, and days\_late greater than 0](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/router-conditions-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=727acf660bb1907b79aa901e99170325)

**3. Connect it, and connect Else**

Connect each condition to its step, and connect **Else** to where the call should go when nothing matches.

On a call, the router checks its conditions one by one and takes the first that matches. If none matches, it takes **Else**. If **Else** isn't connected, the call ends.

### Operators

The same operators are used by **Equation**, **Skip if**, **When a live variable matches** and **Offer it only when**.

| Operator | True when |
| - | - |
| **Equals (=)** | The value is exactly the same text (case matters) |
| **Does not equal (≠)** | The value is different text |
| **Greater than (>)** | Both sides are numbers and the value is larger |
| **Smaller than (\<)** | Both sides are numbers and the value is smaller |
| **Greater than or equal to (≥)** | Both sides are numbers and the value is larger or the same |
| **Smaller than or equal to (≤)** | Both sides are numbers and the value is smaller or the same |
| **Contains (∋)** | The value includes the text |
| **Does not contain (∌)** | The value doesn't include the text |
| **Exists (∃)** | The variable has a value that isn't blank |
| **Does not exist (∄)** | The variable is missing or blank |
| **Matches regex (.\*)** | The pattern is found anywhere in the value. Start with `^` and end with `$` to match the whole value. Use the regex tester to try it |

How values are compared:

* Every variable is stored as text. **Equals** and **Contains** compare text, so `10` and `10.0` are different.
* With >, ≥, \< and ≤, both sides must read as numbers. If either doesn't (for example `$100` or `ten`), the condition is false.
* If the variable has no value at all, every operator except **Exists** and **Does not exist** is false. That includes **Does not equal** and **Does not contain**.

## Delete a transition

Open the transition's settings and click **Delete transition** at the bottom, or hover the transition on the card and click its ×. The transition and its connection are removed. Fixed transitions, such as **On Success** and **Else**, can't be deleted.

## Skip if

**Skip if** ("Skip this node when conditions are met") lets a step step aside when it isn't needed: skip "What's your name?" when `customer_name` already has a value, or skip a Tool step that looks up an order you already have. Every step except Start and End call can have one.

When the call reaches the step, its **Skip if** rules are checked first. If one matches, the call goes straight to that transition's step: the skipped step doesn't speak, doesn't call its API or transfer, and doesn't set its variables. Rules use the [operators above](#operators).

## When a live variable matches

**When a live variable matches** ("Rules on live variables") moves the call as soon as a [live variable](https://docs.tryhamsa.com/agents/variables/live-variables.md) takes a value you care about. Use it for things the caller can say at any moment, such as asking for a person.

It's available on Conversation and Start steps once the step has live variables ("Add live variables in Global settings first."). Its rules can only use live variables.

* **On arrival:** if a rule already holds when the call reaches the step, the call moves on without the step speaking. It won't jump back to a step it has already passed through on the way.
* **After each caller turn:** live variables are updated in the background. When an update changes a variable a rule reads and the rule now holds, the call moves to that rule's step. If the agent had started a reply, the reply is cut off so the next step can answer.
* If several rules hold, the first one wins.

## DTMF input

**DTMF input** ("Keypad input detection") is taken when the caller presses a key on their phone. It's offered on Conversation and Start steps. The key works the moment it's pressed, even while the agent is speaking. See [Keypad input](https://docs.tryhamsa.com/agents/flow/keypad-input.md).

## Auto and After user replies

These two move the call on without the model choosing.

| Type | What happens |
| - | - |
| **Auto** ("Auto-advance when node completes") | The step plays its message, waits for it to finish, then moves on. The caller isn't asked anything. Conversation steps only |
| **After user replies** ("Advance after the user replies") | The step plays its message and waits. As soon as the caller finishes speaking, the step's **Variable on node exit** variables are taken from what was said and the call moves on. The step gives no reply of its own: the next step answers. Conversation and Start steps |

A step can have only one of them, and nothing else. Adding one asks first ("Add this transition?"), then turns off the step's other transitions and deletes their connections. Removing it turns the others back on, but you have to draw their connections again.

## Return to source

**Return to source** sends the call back to the step it came from: "Return to the calling node when the user's reply matches". Use it on a step the caller can reach from several places, such as a "Check opening hours" step, so it can hand the call back to wherever the caller was.

* Write its condition like a prompt transition, for example "The caller has what they needed and wants to carry on." The model takes it when the caller's reply fits.
* It needs no connection on the canvas: the target is the step that led here on this call.
* Each step remembers its own source, also after the call comes back to it.
* It isn't offered while the step has nowhere to go back to, for example when the call started there.

This is separate from a global step's **Return to source after execution**. See [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md#return-to-the-step-the-caller-was-in).

What the fixed transitions mean is on each [step type page](https://docs.tryhamsa.com/agents/flow/steps/overview.md). In short: a Tool step takes **On Success** when the API call works and **On Failure** when it doesn't; a transfer takes **On Failure** when the transfer can't be made; a router takes **Else** when no condition matches.

## How it works on a call

When the call reaches a Conversation step (or a Start step in conversation mode), this happens in order:

1. The step's interruption setting is applied.
2. **Skip if** rules are checked. A match moves the call on at once.
3. **When a live variable matches** rules are checked. A match moves the call on at once.
4. The step's local variables are set.
5. The message plays. With **Auto**, the call then moves on.
6. The step waits for the caller if it has a **Prompt**, **DTMF input**, **After user replies** or **When a live variable matches** transition, or if the flow has any global step.

While the step waits, each caller turn is handled like this: a key press is matched against **DTMF input** transitions; with **After user replies**, the call moves on; otherwise the model replies and may take a prompt transition or a global step, and live variable rules are checked after the background update.

Steps that don't wait for the caller (Router, Tool, Set local variables and so on) run one after another until the call reaches a step that waits, a transfer, or an End call step.

## Good to know

* A Conversation step with no **Prompt**, **DTMF input**, **After user replies**, live variable or **Auto** transition, in a flow with no global steps, speaks its message and stays there: the call has no way to leave it except the caller hanging up.
* Variables hold text. A true or false value reads `True` or `False`, so compare with that exact text.
* `current_time` is a full sentence ("Saturday, October 31, 2026 at 02:05:00 PM UTC"), so you can't compare it as a number. See [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md).
* If an **Offer it only when** rule reads a live variable, the reply can wait briefly (up to 1.5 seconds) for that turn's background update.

## Related

> [card] [Router step](https://docs.tryhamsa.com/agents/flow/steps/router.md)
>
> Branch on variables without the model.

> [card] [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md)
>
> Steps the agent can reach from anywhere.

> [card] [Keypad input](https://docs.tryhamsa.com/agents/flow/keypad-input.md)
>
> DTMF transitions and capturing digits.

> [card] [Extract values from the conversation](https://docs.tryhamsa.com/agents/variables/extracted-variables.md)
>
> Variables on node exit and live variables.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.