LiveKit docs › Prebuilt components › Prebuilt tasks › GetDtmfTask

---

# GetDtmfTask

> Collect keypad (DTMF) or spoken digits from callers for IVR and telephony flows.

Available in (BETA):
- [ ] Node.js
- [x] Python

## Overview

`GetDtmfTask` collects a series of keypad (DTMF) or spoken digits from callers in telephony flows. For example, use this to implement IVR systems that can be navigated by either pressing or speaking numbers.

`GetDtmfTask` handles the following:

- Listening for DTMF tones from the phone keypad.
- Accepting spoken digits as an alternative to DTMF input.
- Waiting for the specified number of digits with a configurable timeout.
- Interrupting the agent when DTMF input is received.

The task returns a `GetDtmfResult` data class with one field: `user_input` (a string of the collected digits).

- **[DTMF example](https://github.com/livekit/agents/blob/main/examples/telephony/basic_dtmf_agent.py)**: A menu-based example that demonstrates using DTMF to collect user input.

- **[Handling DTMF](https://docs.livekit.io/telephony/features/dtmf.md)**: Sending and receiving DTMF in LiveKit telephony apps.

- **[Send DTMF events](https://docs.livekit.io/agents/prebuilt/tools/send-dtmf-events.md)**: Prebuilt tool for sending DTMF tones from your agent to telephony providers.

### Usage

The following example asks the caller to provide a 10-digit phone number and confirms the number with the caller:

```python
from livekit.agents.beta.workflows.dtmf_inputs import GetDtmfTask
from livekit.agents import Agent, function_tool, RunContext

class PhoneAgent(Agent):
    @function_tool()
    async def ask_for_phone_number(self, context: RunContext) -> str:
        """Ask user to provide a phone number."""
        result = await GetDtmfTask(
            num_digits=10,
            chat_ctx=context.session.chat_ctx.copy(
                exclude_instructions=True, 
                exclude_function_call=True
            ),
            ask_for_confirmation=True,
            extra_instructions=(
                "Let the caller know you'll record their 10-digit phone number "
                "and that they can speak or dial it, then capture the digits."
            ),
        )
        
        return f"User's phone number is {result.user_input}"

```

### Parameters

For a full list of parameters, see the [GetDtmfTask reference](https://docs.livekit.io/reference/python/livekit/agents/beta/workflows/dtmf_inputs.html.md#livekit.agents.beta.workflows.dtmf_inputs.GetDtmfTask).

- **`extra_instructions`** _(string)_ (optional): Extra instructions to add to the task.

- **`chat_ctx`** _(ChatContext)_: The chat context to use for the task.

- **`num_digits`** _(int)_: Number of digits to collect. Must be greater than 0.

- **`ask_for_confirmation`** _(bool)_ (optional) - Default: `False`: Whether to ask the user to confirm the collected digits before finalizing (for example, by reading them back). When `True`, the task uses a confirmation flow.

- **`dtmf_input_timeout`** _(float)_ (optional) - Default: `4.0`: Per-digit timeout in seconds while waiting for DTMF or spoken input.

- **`dtmf_stop_event`** _(DtmfEvent)_ (optional) - Default: `DtmfEvent.POUND`: The DTMF event to stop collecting inputs (default `#`).

---

This document was rendered at 2026-06-07T11:35:48.422Z.
For the latest version of this document, see [https://docs.livekit.io/agents/prebuilt/tasks/get-dtmf.md](https://docs.livekit.io/agents/prebuilt/tasks/get-dtmf.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).