Skip to main content
This page covers structural and naming conventions for flow agents. Additional best practices from the Hamsa engineering team will be added here over time.

​
Node Naming

Use descriptive, action-oriented names that make the flow self-documenting: 
✅ Welcome_and_Identify_Caller
✅ Collect_Account_Number
✅ Route_by_Issue_Type
✅ Transfer_to_Billing_Specialist

❌ Node 1
❌ Router
❌ Conversation

​
Variable Naming

All variable names must be snake_case (lowercase, underscores, starts with a letter): 
✅ customer_name
✅ account_balance
✅ issue_category

❌ customerName     (camelCase)
❌ Customer-Name    (kebab-case)
❌ customer name    (spaces)
Use specific, descriptive names rather than generic ones: 
✅ account_number, customer_id, payment_status
❌ number, id, status

​
Always Include a Fallback Transition

Every node that has conditional transitions needs an Always transition as a fallback. Without it, the conversation can stall if no conditions match. 
Transitions:
  - Natural: "billing question" → Billing
  - Natural: "technical issue" → Tech
  - Always → General_Help    # Required fallback

​
Use Extracted Variables Carefully

Extracted variables are only available after the node that collects them. Do not reference an extracted variable in a transition or node that comes before it in the flow. Global node conditions cannot use extracted variables — use system variables or custom variables there instead.

​
Provide Fallback Values in Messages

Use fallback syntax when referencing variables that might not be set: 
"Hello {{customer_name || 'there'}}, your balance is {{balance || 'unavailable'}}."

​
Next Steps

Global Settings

Configure agent-level defaults

Node Types

Learn about all 8 node types

Transitions

Understand transition types and priority

Debugging

Validate and test your flow