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)

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.

---

Prompt Transitions (Natural Language)

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

Configuration

{
  type: 'natural_language',
  prompt: string,       // Condition description (required)
  description?: string
}

Examples

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

{
  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

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.

Examples

Single condition:

Variable: account_status
Operator: equals
Value: 'active'
→ Target: Active_Account_Path

AND logic (all conditions must pass):

Logic: all
Conditions:
  - account_balance > 1000
  - account_type equals "premium"
→ Target: VIP_Path

OR logic (any condition passes):

Logic: any
Conditions:
  - support_tier equals "platinum"
  - is_enterprise equals true
→ Target: Priority_Support

Existence check:

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.

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 for full documentation on all DTMF capabilities.

Configuration

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

Example

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

{
  type: 'auto',
  description: string   // Defaults to "Auto-advance"
}

Example

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

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

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

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

---

Next Steps

Global Nodes

Nodes reachable from anywhere in the flow

DTMF Features

Full keypad interaction documentation

Variables

Variables used in equation conditions

Router Node

Pure routing without conversation