> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 播放按键音

## 概述

按键触摸音工具可让 ElevenLabs 智能体在通话期间播放 DTMF（双音多频）音，即你按下电话键盘数字时发出的声音。借此，智能体可与自动电话系统交互、浏览语音菜单、输入分机号和 PIN 码，并执行其他通常需要人工来电者按电话键盘的按键操作。

此系统工具支持标准 DTMF 音（0-9、\*、#）以及用于控制时机的暂停命令。它可无缝配合 Twilio 和 SIP 中继电话集成，自动为底层电话基础设施生成相应的音频音调。

如需改为收集来电者输入的按键数字，请参阅 [DTMF 输入](/docs/zh/eleven-agents/customization/multimodal-input#dtmf-input)。

## 功能

* **标准 DTMF 音**：支持所有标准键盘字符（0-9、\*、#）
* **暂停控制**：包含用于精确控制时机的暂停命令（w = 0.5 秒，W = 1.0 秒）
* **多提供商支持**：兼容 Twilio 和 SIP 中继集成

此系统工具可用于浏览电话菜单、输入分机号和代码。
LLM 会根据对话上下文决定何时播放哪些音调。

默认工具描述会向驱动对话的 LLM 说明其可以播放这些音调，
建议更新智能体的系统提示词，明确智能体应在何时调用此工具。

**参数：**

* `reason`（字符串，可选）：播放 DTMF 音调的原因（例如“导航至分机”“输入 PIN”）
* `dtmf_tones`（字符串，必填）：要播放的 DTMF 序列。有效字符：0-9、\*、#、w（0.5 秒暂停）、W（1 秒暂停）

**函数调用格式：**

```json
{
  "type": "function",
  "function": {
    "name": "play_keypad_touch_tone",
    "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
  }
}
```

## 带外 DTMF

默认情况下，DTMF 音会作为语音流中的带内音频信号发送。不过，某些 IVR（交互式语音应答）系统可能因音频压缩、网络状况或系统配置，无法可靠检测这些带内音调。

带外 DTMF（RFC 4733）会将音调作为单独的 RTP 数据包而非音频发送。对于接收方 IVR 系统难以检测标准带内 DTMF 的 SIP 中继实现，此方法更加可靠。

要启用带外 DTMF：

1. 前往智能体的工具配置
2. 选择 **播放按键触摸音** 工具
3. 勾选 **使用带外 DTMF（RFC 4733）** 复选框

> **Note**
>
> 带外 DTMF 仅适用于 SIP 中继通话。对于 Twilio
> Native 集成通话，此设置将被忽略。

## 支持的字符

该工具支持以下 DTMF 字符和命令：

* **数字**：`0`、`1`、`2`、`3`、`4`、`5`、`6`、`7`、`8`、`9`
* **特殊音调**：`*`（星号）、`#`（井号）
* **暂停命令**：
  * `w` - 短暂停（0.5 秒）
  * `W` - 长暂停（1.0 秒）

## API 实现

通过 API 创建或更新智能体时，可以配置 `play_keypad_touch_tone` 系统工具。此工具除启用外无需额外配置参数。

```python
from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, I can help you navigate phone systems. How can I assist you today?",
            prompt={
                "prompt": "You are a helpful assistant that can interact with phone systems.",
                "built_in_tools": {
                    "play_keypad_touch_tone": {
                        "type": "system",
                        "name": "play_keypad_touch_tone",
                        # Optional custom description
                        "description": "Play DTMF tones to interact with automated phone systems.",
                        "params": {"system_tool_type": "play_keypad_touch_tone"},
                    }
                },
            },
        ),
    ),
)
```

```javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY",
});

await elevenlabs.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hi, I can help you navigate phone systems. How can I assist you today?",
      prompt: {
        prompt: "You are a helpful assistant that can interact with phone systems.",
        builtInTools: {
          playKeypadTouchTone: {
            type: "system",
            name: "play_keypad_touch_tone",
            description: "Play DTMF tones to interact with automated phone systems.", // Optional custom description
            params: {
              systemToolType: "play_keypad_touch_tone",
            },
          },
        },
      },
    },
  },
});
```

> **Note**
>
> 此工具仅在由 Twilio 或 SIP 中继支持的进行中通话内有效。在电话对话上下文外调用时，
> 将返回错误。