Start Node - Hamsa API

Overview

The start node is the entry point for every flow agent. It’s the first node executed when a call begins and must be present in every flow (you cannot delete it). Unlike other node types, the start node can operate in two distinct modes: conversation mode for greeting callers, or tool mode for pre-fetching data before any conversation begins.

Every flow has exactly one start node. It cannot be deleted, but it can be configured in multiple ways to match your needs.

Operating Modes

Conversation Mode (Default)

In conversation mode, the start node behaves like a standard conversation node—greeting the caller and initiating dialogue. Best for:

Standard flows that begin with a greeting
IVR-style menus with DTMF options
Flows where immediate conversation is needed
Initial qualification or triage

Tool Mode

In tool mode, the start node executes a tool before any conversation happens, allowing you to pre-fetch caller data or perform initial setup actions. Best for:

Looking up caller information from CRM
Checking account status before greeting
Pre-loading personalized data
Logging call initiation
Fetching context from external systems

Configuration: Conversation Mode

Basic Setup

{
  type: "start",
  subType: "conversation",
  messageType: "prompt" | "static",
  message: string,

  // Optional: Variable extraction
  extractVariables: {
    enabled: boolean,
    variables: Variable[]
  }
}

Message Types

Prompt (Dynamic)

The AI generates responses based on context and conversation flow.

Start Node (Conversation - Prompt):
  subType: conversation
  messageType: prompt
  message: |
    ## Objective
    Welcome the caller warmly and identify their reason for calling.

    ## Instructions
    - Greet them professionally
    - Ask how you can help today
    - Listen for their main concern
    - Be friendly and patient

AI might say:

“Good morning! Thanks for calling Acme Corporation. How can I help you today?”
“Hi there! This is Acme Corp. What can I do for you?”

Static (Fixed)

The AI speaks exactly what you write, every time.

Start Node (Conversation - Static):
  subType: conversation
  messageType: static
  message: 'Thank you for calling Acme Corporation. This call may be recorded for quality assurance. How may I help you today?'

AI always says exactly this message.

DTMF Transitions

Start nodes in conversation mode support DTMF transitions for IVR-style menus. Example - Department Selection Menu:

Start Node (Conversation):
  messageType: static
  message: 'Welcome to Acme Corp. Press 1 for Sales, Press 2 for Support, Press 3 for Billing, or stay on the line to speak with an agent.'

  Transitions:
    - DTMF: key=1 → Sales_Department
    - DTMF: key=2 → Support_Department
    - DTMF: key=3 → Billing_Department
    - Always → General_Agent

DTMF transitions are evaluated immediately when the user presses a key, even while the agent is still speaking. This provides a responsive IVR experience.

Variable Extraction

Extract data from the initial conversation to use throughout the flow.

Start Node (Conversation):
  messageType: prompt
  message: "Welcome! May I have your name and account number to get started?"

  Extract Variables:
    enabled: true
    variables:
      - name: customer_name
        description: "Customer's full name"
        extractionPrompt: "Extract the customer's full name"
        dataType: string
        isRequired: true

      - name: account_number
        description: "Account number"
        extractionPrompt: "Extract the account number (digits only)"
        dataType: string
        isRequired: true

  Transitions:
    - Natural Language: "Name and account number collected" → Verify_Account

→ Learn More: Variable Extraction

Configuration: Tool Mode

Basic Setup

{
  type: "start",
  subType: "tool",

  // Tool configuration is in agentSettings.tools where tool.nodeId === 'start'
  // No tool reference fields on the node itself

  // Error handling
  timeout: number,  // milliseconds, default 30000
  onErrorBehavior: "continue" | "retry" | "fail",
  errorMessage?: string,

  // Response customization
  overrideResponse: boolean,
  customResponse?: string,
  outputMapping: Record<string, string>,

  // Processing message
  processingMessage?: string,
  processingMessageType: "static" | "prompt"  // Default: "static"
}

Tool Reference: When subType is ‘tool’, the tool configuration is stored in agentSettings.tools array where tool.nodeId === 'start'. The node itself doesn’t contain tool details—only execution settings.

Selecting a Tool

When you switch to tool mode, you select from your tool library:

Click on the start node
Change Sub Type to “Tool”
Click Select Tool
Choose from your tool templates

What happens behind the scenes:

Selecting a tool creates an entry in agentSettings.tools array
This entry has nodeId: 'start' to link it to the start node
Tool configuration (toolId, toolType, parameters, overrides) is stored in that entry
The start node itself only contains execution settings (timeout, error handling, output mapping)

Available tool types:

API Request (Function): HTTP requests to external APIs
MCP Server: Model Context Protocol integrations
Web Tool: Browser-based tools for SDK deployments

[→ Learn more about tools and configuration/features/tools)

Parameter Mapping

Parameters and overrides are configured in the tool reference (stored in agentSettings.tools), not on the node itself. Example - Caller Lookup:

# In agentSettings.tools array:
Tool Reference:
  nodeId: 'start' # Links to start node
  toolId: 'crm-lookup-tool-id'
  toolType: 'FUNCTION'
  persistentId: 'crm_lookup'
  version: 1
  overrides:
    parameters:
      phone_number: { { caller_id } } # System variable
      include_history: true # Static value
      fields: 'name,account,status' # Static value

# On the start node:
Start Node (Tool):
  subType: tool
  timeout: 10000
  onErrorBehavior: continue

  outputMapping:
    customer_name: $.data.name
    customer_id: $.data.id
    account_status: $.data.account.status
    membership_tier: $.data.account.tier

  processingMessage: 'Please hold while I look up your information...'
  processingMessageType: static

  transitions:
    - Always → Personalized_Greeting

When you configure a tool in the UI, you don’t need to manually edit the agentSettings.tools array. The interface handles the tool reference creation and linkage automatically.

Output Mapping

Extract data from tool responses into flow variables using JSON path syntax. Response from CRM tool:

{
  "data": {
    "id": "CUST-12345",
    "name": "John Smith",
    "account": {
      "status": "active",
      "tier": "premium"
    }
  }
}

Output mapping:

Output Mapping:
  customer_name: $.data.name # "John Smith"
  customer_id: $.data.id # "CUST-12345"
  account_status: $.data.account.status # "active"
  membership_tier: $.data.account.tier # "premium"

Use extracted variables in next node:

Conversation Node: Personalized_Greeting
  message: "Welcome back, {{customer_name}}! As a {{membership_tier}} member, I'm happy to help you today."

Error Handling

Configure what happens when tool execution fails. Continue (Recommended)

Error Handling:
  onErrorBehavior: continue
  errorMessage: "I'm having trouble accessing your account. Let's continue anyway."

Flow continues to next node even if tool fails. Use for non-critical operations. Retry

Error Handling:
  onErrorBehavior: retry
  errorMessage: 'Let me try that again...'

Automatically retries the tool call. Use for intermittent failures. Fail

Error Handling:
  onErrorBehavior: fail
  errorMessage: "I'm experiencing technical difficulties. Please try again later."

Stops flow execution. Use when tool is critical to conversation.

Custom Response Override

By default, the agent handles tool results silently. You can override this to speak custom messages. Without override (silent):

Start Node (Tool):
  tool: Lookup_Caller
  overrideResponse: false
  # Agent says nothing, just transitions to next node

With override (custom message):

Start Node (Tool):
  tool: Lookup_Caller
  overrideResponse: true
  customResponse: "Welcome back, {{customer_name}}! I see you're a {{membership_tier}} member with an {{account_status}} account."
  # Agent speaks this custom message using extracted variables

Processing Message

Show a message while the tool executes (especially useful for slow APIs). Static processing message:

Processing Message:
  message: 'One moment while I look up your information...'
  messageType: static

Dynamic processing message:

Processing Message:
  message: 'Let me check your account details.'
  messageType: prompt

Timeout Configuration

Set maximum wait time for tool execution.

Tool Settings:
  timeout: 10000 # 10 seconds

Default: 30000ms (30 seconds).

If a tool exceeds the timeout, it follows the onErrorBehavior setting.

Use Cases

Use Case 1: Standard Greeting (Conversation Mode)

Scenario: Simple customer service greeting.

Start Node (Conversation):
  subType: conversation
  messageType: static
  message: "Thank you for calling Acme Corporation. How can I help you today?"

  Transitions:
    - Natural Language: "User needs sales" → Sales_Flow
    - Natural Language: "User needs support" → Support_Flow
    - Always → General_Conversation

Scenario: Department routing with keypad.

Start Node (Conversation):
  subType: conversation
  messageType: static
  message: 'Welcome to Acme Corp. For Sales, press 1. For Support, press 2. For Billing, press 3. Or press 0 for the operator.'

  Transitions:
    - DTMF: key=1 → Sales_Department
    - DTMF: key=2 → Support_Department
    - DTMF: key=3 → Billing_Department
    - DTMF: key=0 → Operator_Transfer
    - Always → No_Input_Handler

Use Case 3: Personalized Greeting (Tool Mode)

Scenario: Look up caller, greet by name.

Start Node (Tool):
  subType: tool
  tool: Lookup_Customer_By_Phone

  Parameters:
    phone_number: { { caller_id } }

  Output Mapping:
    customer_name: $.name
    customer_tier: $.tier
    last_order_date: $.last_order

  Custom Response:
    overrideResponse: true
    customResponse: 'Welcome back, {{customer_name}}! How can I help you today?'

  Processing Message:
    message: 'Please hold while I pull up your account...'

  Transitions:
    - Always → Main_Conversation

Use Case 4: Account Status Check (Tool Mode)

Scenario: Check if account is active before proceeding.

Start Node (Tool):
  subType: tool
  tool: Check_Account_Status

  Parameters:
    phone: {{caller_id}}

  Output Mapping:
    account_status: $.status
    account_balance: $.balance
    account_id: $.id

  Error Handling:
    onErrorBehavior: continue
    errorMessage: "I couldn't find your account in our system. Let's verify your information."

  Transitions:
    - Equation: {{account_status}} == "active" → Active_Account_Flow
    - Equation: {{account_status}} == "suspended" → Suspended_Account_Flow
    - Always → New_Customer_Flow

Use Case 5: Call Logging (Tool Mode)

Scenario: Log call start for analytics.

Start Node (Tool):
  subType: tool
  tool: Log_Call_Initiation

  Parameters:
    caller_id: { { caller_id } }
    call_id: { { call_id } }
    timestamp: { { current_time } }
    agent_id: { { agent_id } }

  Error Handling:
    onErrorBehavior: continue
    # Silent failure - logging shouldn't block conversation

  Transitions:
    - Always → Welcome_Greeting

Use Case 6: Multi-Language Routing (Conversation + Tool)

Scenario: Detect language, route to appropriate agent.

Start Node (Conversation):
  subType: conversation
  messageType: static
  message: "Welcome to Acme Corporation. For English, press 1. Para español, oprima 2."

  Transitions:
    - DTMF: key=1 → English_Flow
    - DTMF: key=2 → Transfer_Spanish_Agent

Transfer Agent Node: Transfer_Spanish_Agent
  agentId: "spanish-support-agent"
  transferMessage: "Let me connect you with our Spanish representative."

Flow Examples

Example 1: Simple Customer Service

Example 2: Personalized Experience

Example 3: IVR with Operator Fallback

Troubleshooting

Issue: Tool not appearing in selection

Possible causes:

Tool is inactive
Tool not in current project
Browser cache issue

Solution:

Verify tool is active in tool library
Refresh the page
Check tool project ownership

Issue: Tool times out

Possible causes:

API is slow
Timeout set too low
Network connectivity

Solution:

Increase timeout value
Check API performance
Add retry logic
Use “continue” behavior to avoid blocking

Issue: Variables not extracted from tool response

Possible causes:

Incorrect JSON path in output mapping
API response format changed
Variable name mismatch

Solution:

Check tool response format
Verify JSON path syntax ($.data.field)
Test with API directly
Review output mapping configuration

Issue: DTMF not working on start node

Possible causes:

Transitions not configured correctly
DTMF key not selected
Using tool mode (DTMF only works in conversation mode)

Solution:

Ensure start node is in conversation mode
Verify DTMF transitions are configured
Test with actual phone call

Issue: Custom response not spoken

Possible causes:

overrideResponse is false
customResponse is empty
Variables referenced don’t exist

Solution:

Set overrideResponse: true
Provide custom response text
Verify variable names match output mapping

Schema Reference

Conversation Mode Schema

{
  type: "start",
  subType: "conversation",

  // Message configuration
  messageType: "static" | "prompt",
  message: string,  // Required

  // Variable extraction
  extractVariables: {
    enabled: boolean,
    variables: Array<{
      name: string,
      description?: string,
      dataType: "string" | "number" | "boolean",
      isRequired: boolean,
      extractionPrompt?: string
    }>
  }
}

Tool Mode Schema

{
  type: "start",
  subType: "tool",

  // Tool configuration is stored in agentSettings.tools where tool.nodeId === 'start'
  // Tool selection, parameters, and overrides are NOT on the node

  // Execution settings
  timeout: number,  // milliseconds, default 30000
  onErrorBehavior: "continue" | "retry" | "fail",  // default: "continue"
  errorMessage?: string,

  // Response customization
  overrideResponse: boolean,  // default: false
  customResponse?: string,
  outputMapping: Record<string, string>,  // JSON path mapping, default: {}

  // Processing message
  processingMessage?: string,
  processingMessageType: "static" | "prompt"  // default: "static"
}

Where is the tool configuration? The tool itself (including toolId, toolType, parameters, overrides, etc.) is configured in the agentSettings.tools array. The start node in tool mode only contains execution and response settings, not the tool reference itself.

Next Steps

Conversation Node

Continue the conversation after start

Tool Node

Execute additional tools in your flow

Router Node

Route based on extracted variables

Transitions

Learn about all transition types

Variables

Master the variable system

DTMF Features

Understand DTMF capabilities

​Overview

​Operating Modes

​Conversation Mode (Default)

​Tool Mode

​Configuration: Conversation Mode

​Basic Setup

​Message Types

​Prompt (Dynamic)

​Static (Fixed)

​DTMF Transitions

​Variable Extraction

​Configuration: Tool Mode

​Basic Setup

​Selecting a Tool

​Parameter Mapping

​Output Mapping

​Error Handling

​Custom Response Override

​Processing Message

​Timeout Configuration

​Use Cases

​Use Case 1: Standard Greeting (Conversation Mode)

​Use Case 2: IVR Menu (Conversation Mode + DTMF)

​Use Case 3: Personalized Greeting (Tool Mode)

​Use Case 4: Account Status Check (Tool Mode)

​Use Case 5: Call Logging (Tool Mode)

​Use Case 6: Multi-Language Routing (Conversation + Tool)

​Flow Examples

​Example 1: Simple Customer Service

​Example 2: Personalized Experience

​Example 3: IVR with Operator Fallback

​Troubleshooting

​Issue: Tool not appearing in selection

​Issue: Tool times out

​Issue: Variables not extracted from tool response

​Issue: DTMF not working on start node

​Issue: Custom response not spoken

​Schema Reference

​Conversation Mode Schema

​Tool Mode Schema

​Next Steps

Conversation Node

Tool Node

Router Node

Transitions

Variables

DTMF Features

Overview

Operating Modes

Conversation Mode (Default)

Tool Mode

Configuration: Conversation Mode

Basic Setup

Message Types

Prompt (Dynamic)

Static (Fixed)

DTMF Transitions

Variable Extraction

Configuration: Tool Mode

Basic Setup

Selecting a Tool

Parameter Mapping

Output Mapping

Error Handling

Custom Response Override

Processing Message

Timeout Configuration

Use Cases

Use Case 1: Standard Greeting (Conversation Mode)

Use Case 2: IVR Menu (Conversation Mode + DTMF)

Use Case 3: Personalized Greeting (Tool Mode)

Use Case 4: Account Status Check (Tool Mode)

Use Case 5: Call Logging (Tool Mode)

Use Case 6: Multi-Language Routing (Conversation + Tool)

Flow Examples

Example 1: Simple Customer Service

Example 2: Personalized Experience

Example 3: IVR with Operator Fallback

Troubleshooting

Issue: Tool not appearing in selection

Issue: Tool times out

Issue: Variables not extracted from tool response

Issue: DTMF not working on start node

Issue: Custom response not spoken

Schema Reference

Conversation Mode Schema

Tool Mode Schema

Next Steps