Transfer Call Node

Overview

Transfer call nodes transfer the active phone call to another phone number. This is useful for escalating to human agents, routing to specialized departments, or connecting callers to specific phone lines. Transfer call nodes support both warm transfers (with announcement) and cold transfers (immediate connection). Key characteristic: Transfer call nodes connect the caller to a completely different phone number, ending the AI agent’s involvement in the conversation.

When to Use

Use transfer call nodes to:

Escalate to human agents - Complex issues requiring human judgment
Department routing - Transfer to sales, support, billing departments
Specialist connection - Route to subject matter experts
After-hours routing - Transfer to answering service outside business hours
Emergency scenarios - Critical situations requiring immediate human attention
Geographic routing - Connect to local office phone numbers
Compliance requirements - Legal or regulatory requirements for human interaction

Use Transfer Call Node when:

Caller needs to speak with a person at a phone number
Issue is beyond AI agent’s capabilities
Regulatory or compliance requirements demand human interaction
Specialized expertise is required

Use Transfer Agent Node instead when:

Transferring to another Hamsa AI agent
Want to maintain conversation context and history
Need faster, more reliable handoff
Staying within your AI agent ecosystem

→ Compare: Transfer Agent Node

Core Configuration

{
  type: "transfer_call",
  label?: string,
  description?: string,

  // Phone number (required)
  phoneNumber: string,  // E.164 format: +1234567890

  // Transfer type
  transferType: "warm" | "cold",  // Default: "cold"

  // Transfer message (optional)
  transferMessage?: string,
  transferMessageType: "static" | "prompt",  // Default: "prompt"

  // Timeout
  timeout: number,  // milliseconds, default: 30000

  // Global node settings
  isGlobal?: boolean,
  globalConditionType?: "prompt" | "dtmf",
  globalCondition?: string,
  globalDtmfKey?: string,

  // Transitions (optional - usually none needed)
  transitions?: Transition[]
}

Phone Number Format

Phone numbers must be in E.164 international format.

E.164 Format

+[country code][area code][local number]

Valid examples:

+14155551234   (USA)
+442071234567  (UK)
+61212345678   (Australia)
+33123456789   (France)

Invalid examples:

❌ (415) 555-1234      (Not E.164)
❌ 415-555-1234        (Missing country code)
❌ 14155551234         (Missing + prefix)
❌ +1-415-555-1234     (Contains dashes)

Country Codes

Common country codes:

USA/Canada: +1
UK: +44
Australia: +61
Germany: +49
France: +33

Using Variables

Transfer Call Node: Dynamic_Transfer
  phoneNumber: {{support_phone_number}}
  # Variable must contain E.164 formatted number

Invalid phone number format will cause transfer to fail. Always validate E.164 format.

Transfer Types

Cold Transfer (Default)

Immediately transfer the call without announcement. The caller is connected directly to the destination number.

Transfer Call Node: Operator_Transfer
  phoneNumber: +18005551234
  transferType: cold
  # No transfer message - immediate connection

User experience:

Agent: “Let me transfer you now.”
Call immediately transfers
Caller hears ringing or destination’s greeting
AI agent disconnects

Use cold transfer when:

Speed is important
No context needs to be provided
Destination will identify itself (IVR, receptionist)
Simple, straightforward routing

Warm Transfer

Announce the transfer before connecting. The agent speaks a transfer message, then connects the call.

Transfer Call Node: Sales_Transfer
  phoneNumber: +18005551234
  transferType: warm

  Transfer Message:
    message: "I'm transferring you to our sales team who can better assist you with pricing and packages."
    messageType: static

User experience:

Agent: “I’m transferring you to our sales team…”
Agent speaks full message
Call transfers after message completes
Caller hears ringing or destination’s greeting

Use warm transfer when:

Caller should know why they’re being transferred
Setting expectations about who they’ll reach
Professional, courteous experience
Context or explanation needed

Transfer Message Configuration

Static Message

Exact, predetermined message spoken every time.

Transfer Message:
  message: 'Let me connect you with a specialist who can help. Please hold.'
  messageType: static

Use static when:

Message should be identical every time
Legal or compliance requirements
Scripted professional transfer
No personalization needed

Prompt-Based Message

AI generates contextual transfer message based on conversation.

Transfer Message:
  message: "Explain to the user that you're transferring them to a billing specialist who can help with their account balance question."
  messageType: prompt

AI might say:

“I’m connecting you with our billing team who specializes in account balances.”
“Let me get you to someone in billing who can review your account.”

Use prompt when:

Want natural, conversational transfer
Personalization based on conversation context
Flexible, adaptive messaging
Reference extracted variables

Message with Variables

Use extracted variables in transfer messages.

Transfer Message:
  message: "Thank you {{customer_name}}. I'm transferring you to {{department_name}} now."
  messageType: static

Timeout Configuration

Set maximum wait time for transfer connection.

Transfer Call Node: Support_Transfer
  phoneNumber: +18005551234
  timeout: 45000  # 45 seconds

Default: 30000ms (30 seconds) Range: 1000ms - 60000ms (1-60 seconds) What happens on timeout:

Transfer attempt is cancelled
Call returns to flow (if transitions configured)
Otherwise, call typically ends

Recommendations:

Standard transfers: 30 seconds
Busy departments: 45-60 seconds
Quick routing: 15-20 seconds

If the destination doesn’t answer within the timeout, the transfer fails. Plan for timeout scenarios with fallback transitions.

Custom SIP Headers

Attach custom SIP headers to the outgoing transfer call. This is useful for passing metadata to the receiving SIP endpoint — routing hints, customer context, or authentication tokens. Each header is a key-value pair where the value supports {{variable}} interpolation, making headers dynamic per-call.

Transfer Call Node: Transfer_With_Context
  phoneNumber: +18005551234
  transferType: warm

  sipHeaders:
    - name: X-Customer-Id
      value: "{{customer_id}}"
    - name: X-Call-Reason
      value: "{{call_reason}}"
    - name: X-Priority
      value: "high"

Adding Headers

Click Add Header in the Custom SIP Headers section
Enter the Header Name (e.g., X-Custom-Header)
Enter the Value — either a static string or a {{variable}} reference
Both name and value are required

Use Cases & Examples

Example 1: Simple Operator Transfer

Scenario: Transfer to operator with no announcement.

Transfer Call Node: Operator
  phoneNumber: +18005550100
  transferType: cold

Example 2: Department Routing with Message

Scenario: Route to sales with warm transfer.

Conversation Node: Qualify_Need
  message: "Are you calling about sales, support, or billing?"
  transitions:
    - Natural Language: "sales" → Transfer_Sales
    - Natural Language: "support" → Transfer_Support
    - Natural Language: "billing" → Transfer_Billing

Transfer Call Node: Transfer_Sales
  phoneNumber: +18005551001
  transferType: warm

  Transfer Message:
    message: "I'm connecting you with our sales team who can discuss pricing and packages."
    messageType: static

  timeout: 30000

Example 3: Emergency Transfer (Global)

Scenario: Global node for urgent issues, accessible anytime via DTMF 0.

Transfer Call Node: Emergency_Transfer
  # Global configuration
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 0

  # Transfer configuration
  phoneNumber: +18005550911
  transferType: cold

  Transfer Message:
    message: "Transferring you to emergency support now."
    messageType: static

Example 4: After-Hours Routing

Scenario: Transfer to answering service outside business hours.

Router Node: Business_Hours_Check
  transitions:
    - Structured Equation (logic: all):
        - {{current_hour}} >= 9
        - {{current_hour}} < 17
        - {{current_day_of_week}} != "Saturday"
        - {{current_day_of_week}} != "Sunday"
      → Business_Hours_Flow

    - Always → After_Hours_Transfer

Transfer Call Node: After_Hours_Transfer
  phoneNumber: +18005559999
  transferType: warm

  Transfer Message:
    message: "Our offices are currently closed. I'm transferring you to our after-hours answering service who can take a message or help with urgent matters."
    messageType: static

  timeout: 45000

Example 5: Escalation with Context

Scenario: Transfer with personalized context about the caller.

Tool Node: Lookup_Customer
  outputMapping:
    customer_name: $.name
    account_id: $.id
    issue_type: $.current_issue
  transitions:
    - Always → Escalate_Transfer

Transfer Call Node: Escalate_Transfer
  phoneNumber: +18005552222
  transferType: warm

  Transfer Message:
    message: "Thank you for your patience, {{customer_name}}. I'm transferring you to a specialist who can help with your {{issue_type}} issue. Your account number is {{account_id}}."
    messageType: static

Example 6: VIP Customer Routing

Scenario: High-value customers get direct line to VIP team.

Router Node: Customer_Tier_Check
  transitions:
    - Equation: {{customer_tier}} == "vip"
      → VIP_Transfer
    - Always → Standard_Support

Transfer Call Node: VIP_Transfer
  phoneNumber: +18005550VIP
  transferType: warm

  Transfer Message:
    message: "As a VIP member, I'm connecting you directly with our premium support team."
    messageType: static

  timeout: 20000  # VIP gets faster answer

Example 7: Geographic Routing

Scenario: Transfer to regional office based on location.

Router Node: Region_Router
  transitions:
    - Equation: {{caller_state}} == "CA"
      → West_Coast_Office
    - Equation: {{caller_state}} == "NY"
      → East_Coast_Office
    - Always → National_Line

Transfer Call Node: West_Coast_Office
  phoneNumber: +14155551234
  transferType: warm
  transferMessage: "Connecting you to our San Francisco office."

Transfer Call Node: East_Coast_Office
  phoneNumber: +12125551234
  transferType: warm
  transferMessage: "Connecting you to our New York office."

Example 8: Timeout Fallback

Scenario: Handle transfer timeout with fallback to voicemail.

Transfer Call Node: Attempt_Transfer
  phoneNumber: +18005551234
  timeout: 30000
  transferType: warm
  transferMessage: "Let me connect you with our team."

  # Transitions handle timeout
  transitions:
    - Natural Language: "transfer failed or timeout" → Leave_Voicemail

Conversation Node: Leave_Voicemail
  message: "Our team is currently unavailable. Would you like to leave a message or try again later?"

Global Transfer Nodes

Make transfer nodes accessible from anywhere in the flow.

Global via DTMF

Press a key anytime to transfer (common: 0 for operator).

Transfer Call Node: Global_Operator
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 0

  phoneNumber: +18005550100
  transferType: cold

User can press 0 at any point to immediately transfer.

Global via Natural Language

Speak trigger phrase anytime to transfer.

Transfer Call Node: Global_Human_Agent
  isGlobal: true
  globalConditionType: prompt
  globalCondition: "User wants to speak to a human agent or operator"

  phoneNumber: +18005550100
  transferType: warm
  transferMessage: "I'm connecting you with a live agent now."

User can say “I want to speak to a person” at any point.

Common Global Transfer Patterns

# Operator (DTMF 0)
Transfer Call Node:
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 0
  phoneNumber: +18005550100

# Emergency (DTMF *)
Transfer Call Node:
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: *
  phoneNumber: +18005550911

# Speak to human (Natural language)
Transfer Call Node:
  isGlobal: true
  globalConditionType: prompt
  globalCondition: "User requests human agent, operator, or live person"
  phoneNumber: +18005550100

→ Learn More: Global Nodes

Transitions

Most transfer call nodes don’t need transitions—they terminate the AI agent’s involvement.

When to Use Transitions

Timeout handling:

Transfer Call Node: Busy_Support
  phoneNumber: +18005551234
  timeout: 30000

  transitions:
    - Always → Leave_Voicemail_Option

Conditional flow continuation:

# Rare use case: Continue flow after failed transfer
Transfer Call Node: Optional_Transfer
  transitions:
    - Natural Language: "transfer failed" → Continue_AI_Support
    - Always → End_Call

In practice: Most transfer call nodes have no transitions and simply end the call after transfer.

Troubleshooting

Issue: Transfer fails immediately

Possible causes:

Invalid phone number format
Phone number doesn’t exist
Network connectivity issues
Invalid country code

Solution:

Verify E.164 format: +[country][area][number]
Test phone number manually
Check country code is correct
Remove any spaces, dashes, or parentheses

Issue: Transfer times out

Possible causes:

Destination number not answering
Timeout set too short
Destination line is busy
After-hours (no one available)

Solution:

Increase timeout value
Verify destination is staffed
Test during business hours
Add fallback transition for timeout

Issue: Transfer message not playing

Possible causes:

Using cold transfer (no message in cold transfer)
Message is empty
Message type misconfigured

Solution:

Use transferType: warm for messages
Verify message field has content
Check messageType is set correctly

Issue: User disconnects during transfer

Possible causes:

Long wait time (timeout)
No context provided (user confused)
Unexpected transfer (user didn’t request it)

Solution:

Use warm transfer with explanation
Set appropriate expectations
Reduce wait time
Only transfer when appropriate

Issue: Variables not interpolating in message

Possible causes:

Variable doesn’t exist
Variable name misspelled
Variable not extracted yet

Solution:

Verify variable exists (extracted earlier)
Check spelling: {{exact_variable_name}}
Ensure extraction happens before transfer
Test with static message first

Flow Examples

Example Flow 1: Simple Department Routing

Example Flow 2: Smart Routing with Qualification

Example Flow 3: Escalation Path

Comparison: Transfer Call vs Transfer Agent

Feature	Transfer Call Node	Transfer Agent Node
Destination	Phone number	Hamsa AI agent
Speed	Slower (phone system)	Faster (no phone transfer)
Reliability	Depends on phone network	More reliable
Context	Lost (new call)	Preserved (full history)
User Experience	Hold music, ringing	Seamless transition
Use Case	Human agents, external	Other AI agents
Costs	Telephony transfer costs	No transfer costs
Best For	Escalation to humans	Routing between AI specialists

→ Learn More: Transfer Agent Node

Schema Reference

{
  type: "transfer_call",
  label?: string,
  description?: string,

  // Phone number (required)
  phoneNumber: string,  // E.164 format: +1234567890

  // Transfer type
  transferType: "warm" | "cold",  // Default: "cold"

  // Transfer message (for warm transfers)
  transferMessage?: string,
  transferMessageType: "static" | "prompt",  // Default: "prompt"

  // Timeout
  timeout: number,  // milliseconds, default: 30000 (30 seconds)

  // Custom SIP Headers (optional)
  sipHeaders?: Array<{
    id: string,
    name: string,       // e.g. "X-Custom-Header"
    value: string        // Static value or {{variable}} reference
  }>,

  // Global node settings
  isGlobal?: boolean,
  globalConditionType?: "prompt" | "dtmf",
  globalCondition?: string,  // For prompt-based global
  globalDtmfKey?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#",

  // Transitions (optional)
  transitions?: Transition[],

  // Position
  position: { x: number, y: number }
}

Next Steps

Transfer Agent Node

Transfer to another Hamsa AI agent

Global Nodes

Make transfers accessible anytime

Router Node

Route before transferring

End Call Node

End calls gracefully

DTMF Features

Use keypad for transfer triggers

Best Practices

Build better flows

​Overview

​When to Use

​Core Configuration

​Phone Number Format

​E.164 Format

​Country Codes

​Using Variables

​Transfer Types

​Cold Transfer (Default)

​Warm Transfer

​Transfer Message Configuration

​Static Message

​Prompt-Based Message

​Message with Variables

​Timeout Configuration

​Custom SIP Headers

​Adding Headers

​Use Cases & Examples

​Example 1: Simple Operator Transfer

​Example 2: Department Routing with Message

​Example 3: Emergency Transfer (Global)

​Example 4: After-Hours Routing

​Example 5: Escalation with Context

​Example 6: VIP Customer Routing

​Example 7: Geographic Routing

​Example 8: Timeout Fallback

​Global Transfer Nodes

​Global via DTMF

​Global via Natural Language

​Common Global Transfer Patterns

​Transitions

​When to Use Transitions

​Troubleshooting

​Issue: Transfer fails immediately

​Issue: Transfer times out

​Issue: Transfer message not playing

​Issue: User disconnects during transfer

​Issue: Variables not interpolating in message

​Flow Examples

​Example Flow 1: Simple Department Routing

​Example Flow 2: Smart Routing with Qualification

​Example Flow 3: Escalation Path

​Comparison: Transfer Call vs Transfer Agent

​Schema Reference

​Next Steps

Transfer Agent Node

Global Nodes

Router Node

End Call Node

DTMF Features

Best Practices

Overview

When to Use

Core Configuration

Phone Number Format

E.164 Format

Country Codes

Using Variables

Transfer Types

Cold Transfer (Default)

Warm Transfer

Transfer Message Configuration

Static Message

Prompt-Based Message

Message with Variables

Timeout Configuration

Custom SIP Headers

Adding Headers

Use Cases & Examples

Example 1: Simple Operator Transfer

Example 2: Department Routing with Message

Example 3: Emergency Transfer (Global)

Example 4: After-Hours Routing

Example 5: Escalation with Context

Example 6: VIP Customer Routing

Example 7: Geographic Routing

Example 8: Timeout Fallback

Global Transfer Nodes

Global via DTMF

Global via Natural Language

Common Global Transfer Patterns

Transitions

When to Use Transitions

Troubleshooting

Issue: Transfer fails immediately

Issue: Transfer times out

Issue: Transfer message not playing

Issue: User disconnects during transfer

Issue: Variables not interpolating in message

Flow Examples

Example Flow 1: Simple Department Routing

Example Flow 2: Smart Routing with Qualification

Example Flow 3: Escalation Path

Comparison: Transfer Call vs Transfer Agent

Schema Reference

Next Steps