> ## 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.

# Design flows that hold up on real calls

> Practical advice for flow agents, each tip tied to how calls actually run: transitions, routers, variables, global steps, keypad input and testing.

These tips come from how flow agents behave on calls. Each one says what to do and why, so you can judge when it applies to your flow.

## Write prompt transitions the model can tell apart

The model picks a prompt transition by reading its **When to take this path** text, alongside the trigger conditions of every global step. They have no order, so the model goes by meaning alone.

* Describe what the caller says or wants, not what the agent should do next: "The caller wants to move an existing appointment", not "Go to rescheduling".
* Make each description clearly different from the others on the same step and from your global steps' trigger conditions. Two transitions that both fit the same reply leave the choice to chance.
* Use **Offer it only when** to hide a path until it makes sense, for example offer "Confirm the booking" only when `appointment_time` exists. The model can't take a path it isn't offered.

## Use a router for decisions that must follow a rule

A Router step decides on variables with fixed rules, without the model and without speaking. Use it when the answer must always be the same for the same values, such as routing by plan type or by whether an API returned a record.

* Make the conditions on one router exclusive, so at most one can match. Then the order in which they're checked doesn't matter.
* Always connect **Else**. A router with no match and no connected **Else** ends the call.
* Compare numbers with >, ≥, \< and ≤ only when the value is a plain number. `$100` or "ten" isn't a number, and the condition is false.
* Don't compare times as numbers. `current_time` is a sentence ("Saturday, October 31, 2026 at 02:05:00 PM UTC"). See [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md).

## Give every conversation step a way out

A Conversation step only waits for the caller when it has something to wait for: a **Prompt**, **DTMF input**, **After user replies** or **When a live variable matches** transition, or any global step in the flow. A step with none of these, and no **Auto**, speaks and leaves the call nowhere to go.

Check each Conversation step: either it ends with **Auto**, or at least one transition leads on, or it's followed by an End call step.

## Don't ask for what you already know

* Add **Skip if** to a Conversation step that collects a value you might already have, for example skip "Can I have your name?" when `customer_name` exists. The step is skipped before it speaks.
* A **Variable on node exit** that already has a value isn't asked again; the model can still update it if the caller corrects it.

## Mark variables required only when the next step needs them

A required **Variable on node exit** blocks every prompt transition on the step until it has a valid value, and the model keeps asking for it. That's right for a booking date before a booking call, and wrong for a nice-to-have like an email address. Keep optional what the flow can live without.

**Check the value** rules work the same way: a required value that fails the check holds the call in the step until the caller gives one that passes. Use checks for formats you really rely on, such as a date or a phone number.

## Use live variables for what can come up at any time

[Live variables](https://docs.tryhamsa.com/agents/flow/flow-settings.md#live-variables) are updated after every caller turn, in every step. They suit details a caller may give out of order, such as their name, or a wish to cancel. Pair them with **When a live variable matches** to react the moment they change.

Don't make everything live. A step that uses a live variable can wait up to 1.5 seconds for the background update before it replies. For a value only one step needs, use that step's **Variable on node exit**.

## Keep global steps few and specific

Every global step is offered to the model on every conversation step. A handful of clearly different global steps (speak to a person, opening hours, cancel) works well; many overlapping ones make the model's choice harder.

* Global steps can only use system, dynamic and environment variables plus their own **Variable extraction** variables, because the caller may reach them before giving any details.
* For a quick answer that should bring the caller back, use a global Tool step with **Return to source after execution**.
* Put **Confirm before proceeding** on steps that are hard to undo, such as a transfer or a cancellation, so a misheard request doesn't trigger them.

See [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md).

## Write messages that survive missing values

Step messages use Jinja. An undefined variable renders as empty text, and a syntax error removes every variable from that message.

* Give a fallback: `{{ customer_name or 'there' }}` covers both a missing and an empty value. `{{ customer_name | default('there') }}` covers a missing one.
* Don't use `||`: it's not Jinja, and it empties every variable in the message.

See [Jinja syntax for prompts and messages](https://docs.tryhamsa.com/agents/variables/jinja.md).

## Use Static messages for exact wording

A **Static** message is spoken word for word. A **Prompt** message is instructions the model turns into its own words. Use **Static** for disclosures, legal lines and anything that must be said exactly; use **Prompt** for natural conversation.

## Plan keypad input around the finishing key

Typed digits are saved only when the caller presses a key that has a **DTMF input** transition, `#` or `*`. Always add that transition, and say it in the message: "Type your account number, then press hash." See [Keypad input](https://docs.tryhamsa.com/agents/flow/keypad-input.md).

## Remember that only conversation steps can be interrupted

Callers can interrupt the agent only on Conversation steps (and the Start step's opening message, if allowed). Messages on other steps, such as a transfer message or an End call message, always play to the end. Keep them short.

## Keep large flows readable

* Give every step a clear label. Labels show on the canvas, in **Find**, and in call logs.
* Group the steps of each part of the call (for example "Book appointment") and switch **Show** to **By groups**.
* Use **Auto-layout nodes** after big changes.

See [Work in the flow builder](https://docs.tryhamsa.com/agents/flow/flow-builder.md).

## Test the paths, not only the happy one

* Make a browser test call and watch **Live call logs** and the ring on the active step: they show which step the call is in and why it moved.
* Try the replies that should take each transition, a reply that fits none, and an interruption.
* After a call, open it in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md) and use [**Debug mode**](https://docs.tryhamsa.com/agents/monitor/debug-mode.md) to step through it on the flow, with what was extracted at each step.

See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md).

## Related

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> How the next step is chosen.

> [card] [Write a prompt that works on calls](https://docs.tryhamsa.com/agents/build/write-a-prompt.md)
>
> Prompt advice for any agent.

> [card] [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md)
>
> Reach a step from anywhere.

> [card] [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md)
>
> Transcript, recording and Debug mode.


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