Play keypad touch tone

Overview

The keypad touch tone tool allows Conversational AI 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.

Custom LLM integration

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
}

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
)