Play keypad touch tone

Overview

The keypad touch tone tool allows ElevenLabs agents to play DTMF (Dual-Tone Multi-Frequency) tones during phone calls; these are the tones that are played when you press numbers on your keypad. This enables agents to interact with automated phone systems, navigate voice menus, enter extensions, input PIN codes, and perform other touch-tone operations that would typically require a human caller to press keys on their phone keypad.

This system tool supports standard DTMF tones (0-9, *, #) as well as pause commands for timing control. It works seamlessly with both Twilio and SIP trunking phone integrations, automatically generating the appropriate audio tones for the underlying telephony infrastructure.

Functionality

• Standard DTMF tones: Supports all standard keypad characters (0-9, *, #)
• Pause control: Includes pause commands for precise timing (w = 0.5s, W = 1.0s)
• Multi-provider support: Works with both Twilio and SIP trunking integrations

This system tool can be used to navigate phone menus, enter extensions and input codes. The LLM determines when and what tones to play based on conversation context.

The default tool description explains to the LLM powering the conversation that it has access to play these tones, and we recommend updating your agent’s system prompt to explain when the agent should call this tool.

Parameters:

• reason (string, optional): The reason for playing the DTMF tones (e.g., “navigating to extension”, “entering PIN”)
• dtmf_tones (string, required): The DTMF sequence to play. Valid characters: 0-9, *, #, w (0.5s pause), W (1s pause)

Function call format:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "play_keypad_touch_tone",
5
    "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
6
  }
7
}

Out-of-band DTMF

By default, DTMF tones are sent as in-band audio signals within the voice stream. However, some IVR (Interactive Voice Response) systems may not reliably detect these in-band tones due to audio compression, network conditions, or system configuration.

Out-of-band DTMF (RFC 4733) sends tones as separate RTP packets instead of audio. This method is more reliable for SIP trunking implementations where recipient IVR systems struggle to detect standard in-band DTMF.

To enable out-of-band DTMF:

1. Navigate to your agent’s tool configuration
2. Select the Play keypad touch tone tool
3. Check the Use out-of-band DTMF (RFC 4733) checkbox

Supported characters

The tool supports the following DTMF characters and commands:

• Digits: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
• Special tones: * (star), # (pound/hash)
• Pause commands:
  • w - Short pause (0.5 seconds)
  • W - Long pause (1.0 second)

API Implementation

You can configure the play_keypad_touch_tone system tool when creating or updating an agent via the API. This tool requires no additional configuration parameters beyond enabling it.

1
from elevenlabs import (
2
    ConversationalConfig,
3
    ElevenLabs,
4
    AgentConfig,
5
    PromptAgent,
6
    PromptAgentInputToolsItem_System,
7
    SystemToolConfigInputParams_PlayKeypadTouchTone,
8
)
9
10
# Initialize the client
11
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
12
13
# Create the keypad touch tone tool configuration
14
keypad_tool = PromptAgentInputToolsItem_System(
15
    type="system",
16
    name="play_keypad_touch_tone",
17
    description="Play DTMF tones to interact with automated phone systems.", # Optional custom description
18
    params=SystemToolConfigInputParams_PlayKeypadTouchTone(
19
        system_tool_type="play_keypad_touch_tone"
20
    )
21
)
22
23
# Create the agent configuration
24
conversation_config = ConversationalConfig(
25
    agent=AgentConfig(
26
        prompt=PromptAgent(
27
            prompt="You are a helpful assistant that can interact with phone systems.",
28
            first_message="Hi, I can help you navigate phone systems. How can I assist you today?",
29
            tools=[keypad_tool],
30
        )
31
    )
32
)
33
34
# Create the agent
35
response = elevenlabs.conversational_ai.agents.create(
36
    conversation_config=conversation_config
37
)