> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retoneai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transitions
> Route conversations between stages
Transitions define how and when your voice agent moves from one stage to another. They're the connections (edges) between nodes on the canvas.
## Overview
A transition consists of:
* **Source**: The node where the transition originates
* **Target**: The node where the conversation continues
* **Condition**: What triggers the transition (optional)
```
┌─────────────┐ ┌─────────────┐
│ Source │ ──── Condition ───►│ Target │
│ Node │ │ Node │
└─────────────┘ └─────────────┘
```
## Transition Types
### Any Message
Triggers when the caller says anything.
```yaml theme={null}
Type: any_message
```
**Use cases:**
* Start node → First conversation stage
* After static messages
* When any response should continue the flow
### Immediate
Automatically triggers after the node executes.
```yaml theme={null}
Type: immediate
```
**Use cases:**
* After greeting plays
* After function execution
* Chaining nodes without user input
### Keyword
Triggers when the caller says specific words or phrases.
```yaml theme={null}
Type: keyword
Config:
keywords: ["cancel", "stop", "quit"]
caseSensitive: false
matchType: "contains" # or "exact"
```
**Use cases:**
* IVR-style menus ("say 'sales' for sales")
* Escape phrases ("say 'agent' for a human")
* Command detection
### All Extracted
Triggers when all required variables have been collected.
```yaml theme={null}
Type: all_extracted
```
**Use cases:**
* After Data Extraction completes
* Moving to processing after data collection
* Form completion flows
### Function Success
Triggers when a function call completes successfully.
```yaml theme={null}
Type: function_success
```
**Use cases:**
* After API lookups
* After database operations
* After external integrations
### Timeout
Triggers after a period of silence.
```yaml theme={null}
Type: timeout
Config:
seconds: 10
message: "Are you still there?"
resetOnInput: true
```
**Use cases:**
* Handling unresponsive callers
* Re-prompting after silence
* Ending abandoned calls
### Variable Comparison
Triggers based on a variable value.
```yaml theme={null}
Type: variable_comparison
Config:
variable: "customer_tier"
operator: "=="
value: "premium"
```
**Use cases:**
* Routing based on collected data
* Conditional flow paths
* A/B testing flows
### Condition Prompt
Uses AI to evaluate a natural language condition.
```yaml theme={null}
Type: condition_prompt
Config:
condition: "The customer wants to speak to a human agent"
```
**Use cases:**
* Intent detection
* Sentiment-based routing
* Complex conditional logic
## Transition Priority
When multiple transitions could trigger, they're evaluated in order:
1. **Keyword** - Checked first for exact matches
2. **Condition Prompt** - AI evaluates intent
3. **Variable Comparison** - Checks data values
4. **Timeout** - Fires after silence period
5. **Default/Fallback** - Catches everything else
If no transition matches, the conversation stays in the current node. Always ensure at least one transition can fire.
## Creating Transitions
### From Conversation Nodes
1. Open a Conversation node
2. Scroll to **Transitions** section
3. Click **Add Transition**
4. Enter a condition (natural language)
5. Select the target node
```yaml theme={null}
Condition: "The customer asks about returns or refunds"
Target: Returns Handler
```
### From the Canvas
1. Click the source handle (bottom of node)
2. Drag to the target handle (top of node)
3. Release to create the connection
4. Click the edge to configure
### Edge Labels
Edges display their condition as a label. Click the label to edit.
## Transition Conditions
### Writing Effective Conditions
**Good**: "The customer explicitly asks to speak with a human agent"
**Bad**: "The customer needs help"
**Good**: "The customer says goodbye, thanks you, or indicates they're done"
**Bad**: "The customer says bye"
**Good**: "The customer provides an order number in format XX-123456"
**Bad**: "The customer gives a number"
### Condition Examples
| Scenario | Condition |
| ---------------- | ------------------------------------------------------------------------ |
| Transfer request | "The customer asks to speak with a human, manager, or real person" |
| End conversation | "The customer says goodbye, indicates they're done, or thanks the agent" |
| Billing inquiry | "The customer asks about charges, billing, invoices, or payments" |
| Escalation | "The customer expresses frustration, anger, or threatens to cancel" |
| Confirmation | "The customer confirms, agrees, or says yes" |
| Denial | "The customer declines, disagrees, or says no" |
## Multiple Transitions
Nodes can have multiple outgoing transitions:
```
┌─────────────────┐
│ Conversation │
└────────┬────────┘
│
┌────┴────┬────────────┬────────────┐
│ │ │ │
▼ ▼ ▼ ▼
[Returns] [Billing] [Transfer] [End Call]
Conditions:
- "asks about returns" → Returns
- "asks about billing" → Billing
- "wants human" → Transfer
- "says goodbye" → End Call
```
## Default Transitions
Some nodes require or benefit from a default path:
* **If/Else**: Must have a default for unmatched conditions
* **Conversation**: Consider a default for unexpected intents
* **Data Extraction**: Handle max attempts exceeded
## Testing Transitions
1. Open the **Test** panel
2. Send messages that should trigger each transition
3. Watch the canvas - active transitions highlight in green
4. Verify the flow moves to the expected node
Test edge cases: What happens with unexpected input? Does the flow handle it gracefully?
## Best Practices
For each user intent, there should be exactly one matching transition.
Ensure every possible input has a path forward.
Test each transition with multiple phrasings.
Complex conditions are harder to maintain and debug.
## Debugging Transitions
If transitions aren't firing as expected:
1. **Check condition wording** - Is it too specific or ambiguous?
2. **Test in isolation** - Does the transition work on its own?
3. **Check order** - Is another transition firing first?
4. **Review logs** - What did the AI interpret?
## Related
Primary node for transitions
Variable-based routing
Visual transition management