Skip to main content

GetPhoneNumberTask

Collect and validate a phone number from the user with spoken digit handling.

On this page

Overview Usage Parameters
Available in
Beta
|
Python

Overview

Use GetPhoneNumberTask to collect a phone number from the user. The task normalizes spoken digit patterns and validates the result against international phone number formats.

GetPhoneNumberTask handles the following:

  • Conversion of spoken digits to their numeric form (for example, "five five five" becomes "555").
  • Recognition of "plus" as the international prefix + and "area code" as a verbal cue.
  • Stripping of dashes, spaces, parentheses, and dots.
  • Validation against international phone number formats (7 to 15 digits, with optional leading +).
  • Reading the number back in groups rather than as a single block.

The task returns a GetPhoneNumberResult data class with one field: phone_number.

Usage

The following example uses GetPhoneNumberTask to collect a callback number:

from livekit.agents.beta.workflows import GetPhoneNumberTask
from livekit.agents import function_tool, RunContext


@function_tool()
async def collect_callback_number(context: RunContext) -> str:
    """Collect a callback phone number from the user"""
    phone_result = await GetPhoneNumberTask(
        chat_ctx=context.session.chat_ctx,
        extra_instructions="Ask for a number where we can reach them during business hours.",
    )
    return f"Callback number recorded: {phone_result.phone_number}"

Parameters

For a full list of parameters, see the GetPhoneNumberTask reference.

extra_instructionsstringDefault: ""

Additional instructions to append to the task's default instructions.

chat_ctxChatContext

The conversation history the task-specific LLM sees. If you omit it, the task runs with an empty context, with no memory of what was said earlier in the session. Pass the primary agent's chat context so the task can refer to prior turns and, when used inside a task group, so exchanges are summarized back into the main context.

require_confirmationbool

Whether to read the phone number back to the user to confirm it before finalizing the task. For audio sessions this defaults to True, for text it defaults to False.

toolslist

Additional tools available to the task. Use this to add or substitute function tools.