Skip to main content

GetDtmfTask

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

On this page

Overview Usage Parameters
Available in
Beta
|
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

A menu-based example that demonstrates using DTMF to collect user input.

Handling DTMF

Sending and receiving DTMF in LiveKit telephony apps.

Send DTMF events

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:

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.

extra_instructionsstringOptional

Extra instructions to add to the task.

chat_ctxChatContextRequired

The chat context to use for the task.

num_digitsintRequired

Number of digits to collect. Must be greater than 0.

ask_for_confirmationboolOptionalDefault: 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_timeoutfloatOptionalDefault: 4.0

Per-digit timeout in seconds while waiting for DTMF or spoken input.

dtmf_stop_eventDtmfEventOptionalDefault: DtmfEvent.POUND

The DTMF event to stop collecting inputs (default #).