DTMF Features - Hamsa API

DTMF (Dual-Tone Multi-Frequency) signaling represents keypad button presses (0-9, *, #) in telecommunication systems. Hamsa provides three distinct DTMF features for different use cases.

Overview

Feature	Purpose	Availability	Use Case
Simple Transitions	IVR menu navigation	Conversation & Start nodes	”Press 1 for Sales”
Input Capture	Collect digit sequences	Conversation & Start nodes*	Account numbers, PINs
Global Triggers	Universal keypad shortcuts	All nodes (except web_tool & start)	“Press 0 for operator anytime”

*Start nodes support DTMF input capture but do not have completion condition UI (timeout/termination/digitLimit).

DTMF Processing Flow

DTMF Feature Comparison

Feature 1: Simple DTMF Transitions

Always available on conversation and start nodes. No toggle or special configuration required.

Purpose

Enable IVR-style menu navigation where users press a single key to select an option and advance to a specific node.

How It Works

Create menu options like “Press 1 for Sales, Press 2 for Support” by adding DTMF transitions to your nodes.

Configuration

Add Transition

On a conversation or start node, click ”+ Add Transition”

Select Type

Choose “DTMF” as the transition type

Pick Key

Click a key on the 3×4 keypad grid (0-9, *, #)

Connect Node

Draw an edge to the target node

Example

Conversation Node: 'Welcome! Press 1 for Sales, Press 2 for Support'
├─ Transition: DTMF key=1 → Sales_Department
└─ Transition: DTMF key=2 → Support_Department

Use descriptive auto-generated labels like “Press 1” for clarity in your flow diagram.

Feature 2: DTMF Input Capture

Available on conversation nodes and start nodes. Requires variable name when enabled.Note: Start nodes support DTMF input capture but do not display completion condition UI (timeout/termination/digitLimit). These conditions only appear on conversation nodes.

Purpose

Capture a sequence of DTMF digits (account number, PIN, phone number) and store it in a variable for use throughout your workflow.

How It Works

When enabled, the AI listens for multiple keypad presses and stores the complete sequence in a named variable. Capture completes based on optional conditions.

Configuration

Enable Capture

Open conversation node form → Find “DTMF Input Capture” → Toggle ON

Set Variable Name

Enter variable name (required): account_number, pin_code, etc.Must follow snake_case format: lowercase, underscores allowed, starts with letter

Configure Completion

Set optional conditions (at least one recommended):

Digit Limit: Stop after X digits (1-20)
Termination Key: Stop when user presses #, *, or 0-9
Timeout: Stop after X seconds of no input (1-30)

Schema

{
  enabled: boolean,
  variableName: string,        // Required: ^[a-z][a-z0-9_]*$
  digitLimit?: number,          // Optional: 1-20
  terminationKey?: '0'-'9'|'#'|'*',  // Optional
  timeoutMs?: number           // Optional: 1000-30000
}

Variable Usage

DTMF captured variables are fully integrated into the variable system and available to all downstream nodes.

Once captured, use the variable in:

Message templates: "Your account number is {{account_number}}"
Tool parameters: Pass to API calls
Router conditions: Branch based on value
Subsequent prompts: Reference in any downstream node

Example

Node: Account_Lookup
Message: "Please enter your 6-digit account number followed by pound"

DTMF Input Capture:
  enabled: true
  variableName: account_number
  digitLimit: 6
  terminationKey: #
  timeout: 15 seconds

→ User enters: 1-2-3-4-5-6-#
→ Variable {{account_number}} = "123456"

Next Node (Tool):
  API Call: lookup_customer
  Parameters:
    account_id: {{account_number}}

The captured variable appears on the node with a phone icon badge for easy identification.

DTMF Capture Restriction: When DTMF input capture is enabled on a node, number keys (0-9) cannot be used for DTMF transitions on that same node. Only # and * keys remain available for menu navigation. This prevents conflicts between digit capture and menu options.

Feature 3: Global Node DTMF Triggers

Available on all node types except web_tool and start nodes.

Purpose

Allow global nodes to be triggered from anywhere in the workflow by pressing a specific key, providing quick access to critical functions.

How It Works

When a node is marked as global with DTMF trigger type, pressing the configured key from anywhere in the call immediately activates that node.

Configuration

Enable Global Mode

Open any node form → Find “Global” section → Toggle ON

Select Trigger Type

Choose between:

Natural Language (Prompt): Triggered by speech
Keypad Press (DTMF): Triggered by key press

Configure DTMF Key

If DTMF selected, choose key from keypad gridCommon conventions:

0: Operator/human agent
9: Repeat main menu
*: Go back/previous menu
#: Confirm/submit

Schema

{
  isGlobal: true,
  globalConditionType: 'dtmf',  // or 'prompt'
  globalDtmfKey: '0',          // Required when type='dtmf'
}

Examples

Operator Transfer (DTMF 0)

Transfer Call Node (Global):
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 0
  phoneNumber: +1-800-OPERATOR

→ User can press 0 anytime to reach operator

Conversation Node (Global):
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 9
  message: "Main menu: Press 1 for Sales, 2 for Support"

→ User can press 9 anytime to hear menu again

Emergency Support (DTMF *)

Transfer Call Node (Global):
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: *
  phoneNumber: +1-800-EMERGENCY

→ User can press * anytime for emergency support

Roadmap

Outbound IVR Navigation — the ability for agents to automatically navigate external IVR phone trees when making outbound calls — is not yet available. It is on the roadmap and will be supported in a future release.

Complete IVR Flow Example

Here’s a comprehensive example combining all three DTMF features: Implementation:

Start Node (Conversation):
  message: "Welcome! Press 1 for Sales, 2 for Support, 0 for operator"
  transitions:
    - type: dtmf, key: 1 → Sales_Node
    - type: dtmf, key: 2 → Support_Node

Sales Node (Conversation):
  message: "Please enter your customer ID followed by #"
  dtmfInputCapture:
    enabled: true
    variableName: customer_id
    terminationKey: #
    timeout: 15s
  transitions:
    - type: always → Lookup_Tool

Lookup Tool (Tool):
  tool: lookup_customer
  parameters:
    id: {{customer_id}}  # Uses captured DTMF variable

Operator Node (Transfer Call - Global):
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 0
  phoneNumber: +1-800-OPERATOR

Repeat Menu Node (Conversation - Global):
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 9
  message: "Main menu: Press 1 for Sales, 2 for Support"

Validation

DTMF features are validated at both node and workflow levels. Errors prevent saving until resolved.

Validation Rules

Feature	Field	Requirement	Error
Input Capture	Variable Name	Required when enabled	Must be snake_case format
Simple Transition	DTMF Key	Required	Must select a key
Global Trigger	DTMF Key	Required when type=dtmf	Must select a key

Error Indicators

Node level: Red icon in node header
Workflow level: Errors in workflow header dropdown
Focus button: Navigate to problematic nodes

Troubleshooting

DTMF transitions not working

Possible causes:

Key not selected in popover
Transition not connected to target node
Using on unsupported node type (not conversation/start)

Solution: Verify key selection and node connections

Input capture variable empty

Possible causes:

User didn’t enter any digits
Timeout occurred before input
Variable name typo in usage

Solution: Add validation, check variable name syntax

Global DTMF not triggering

Possible causes:

Node not marked as global
DTMF key not configured
Trigger type set to ‘prompt’ instead of ‘dtmf’

Solution: Verify global settings and trigger type

Validation errors on save

Possible causes:

Missing variable name when input capture enabled
Invalid variable name format
DTMF key not selected

Solution: Check workflow header dropdown, click “Focus” to navigate to errors

Next Steps

Variables

Learn how to use captured variables throughout your flow

Transitions

Master all transition types including DTMF

Router Node

Use captured variables in routing logic

Best Practices

Learn flow agent best practices

Dashboard

Agents

Variables

Tools

Knowledge Base

Batch Calls

Call History

Phone Numbers

Configuration

​Overview

​DTMF Processing Flow

​DTMF Feature Comparison

​Feature 1: Simple DTMF Transitions

​Purpose

​How It Works

​Configuration

​Example

​Feature 2: DTMF Input Capture

​Purpose

​How It Works

​Configuration

​Schema

​Variable Usage

​Example

​Feature 3: Global Node DTMF Triggers

​Purpose

​How It Works

​Configuration

​Schema

​Examples

​Operator Transfer (DTMF 0)

​Repeat Menu (DTMF 9)

​Emergency Support (DTMF *)

​Roadmap

​Complete IVR Flow Example

​Validation

​Validation Rules

​Error Indicators

​Troubleshooting

​Next Steps

Variables

Transitions

Router Node

Best Practices

Overview

DTMF Processing Flow

DTMF Feature Comparison

Feature 1: Simple DTMF Transitions

Purpose

How It Works

Configuration

Example

Feature 2: DTMF Input Capture

Purpose

How It Works

Configuration

Schema

Variable Usage

Example

Feature 3: Global Node DTMF Triggers

Purpose

How It Works

Configuration

Schema

Examples

Operator Transfer (DTMF 0)

Repeat Menu (DTMF 9)

Emergency Support (DTMF *)

Roadmap

Complete IVR Flow Example

Validation

Validation Rules

Error Indicators

Troubleshooting

Next Steps