ivr_navigator

Interactive Voice Response (IVR) navigation components.

This module provides classes for automated navigation of IVR phone systems using LLM-based decision making and DTMF tone generation.

class pipecat.extensions.ivr.ivr_navigator.IVRStatus(*values)

Bases: Enum

Enumeration of IVR navigation status values.

These statuses are used to communicate the current state of IVR navigation between the LLM and the IVR processing system.

DETECTED = 'detected'

COMPLETED = 'completed'

STUCK = 'stuck'

WAIT = 'wait'

class pipecat.extensions.ivr.ivr_navigator.IVRProcessor(*, classifier_prompt: str, ivr_prompt: str, ivr_vad_params: VADParams | None = None)

Bases: FrameProcessor

Processes LLM responses for IVR navigation commands.

Aggregates XML-tagged commands from LLM text streams and executes corresponding actions like DTMF tone generation and mode switching.

Supported features:

• DTMF command processing (<dtmf>1</dtmf>)

• IVR state management (see IVRStatus enum: <ivr>detected</ivr>, <ivr>completed</ivr>, <ivr>stuck</ivr>, <ivr>wait</ivr>)

• Automatic prompt and VAD parameter switching

• Event emission via on_ivr_status_changed for detected, completed, and stuck states

__init__(*, classifier_prompt: str, ivr_prompt: str, ivr_vad_params: VADParams | None = None)

Initialize the IVR processor.

Parameters:

• classifier_prompt – System prompt for classifying IVR or conversation.

• ivr_prompt – System prompt for IVR navigation mode.

• ivr_vad_params – VAD parameters for IVR navigation mode. If None, defaults to VADParams(stop_secs=2.0).

update_saved_messages(messages: list[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam | LLMSpecificMessage]) → None

Update the saved context messages.

Sets the messages that are saved when switching between conversation and IVR navigation modes.

Parameters:

messages – List of context messages to save.

async process_frame(frame: Frame, direction: FrameDirection)

Process frames and aggregate XML tag content.

Parameters:

• frame – The frame to process.

• direction – The direction of frame flow in the pipeline.

class pipecat.extensions.ivr.ivr_navigator.IVRNavigator(*, llm: LLMService, ivr_prompt: str, ivr_vad_params: VADParams | None = None)

Bases: Pipeline

Pipeline for automated IVR system navigation.

Orchestrates LLM-based IVR navigation by combining an LLM service with IVR processing capabilities. Starts with mode classification to classify input as conversation or IVR system.

Navigation behavior:

• Detects conversation vs IVR systems automatically

• Navigates IVR menus using DTMF tones and verbal responses

• Provides event hooks for mode classification and status changes (on_conversation_detected, on_ivr_status_changed)

• Developers control conversation handling via on_conversation_detected event

CLASSIFIER_PROMPT = 'You are an IVR detection classifier. Analyze the transcribed text to determine if it\'s an automated IVR system or a live human conversation.\n\nIVR SYSTEM (respond `<mode>ivr</mode>`):\n- Menu options: "Press 1 for billing", "Press 2 for technical support", "Press 0 to speak to an agent"\n- Automated instructions: "Please enter your account number", "Say or press your selection", "Enter your phone number followed by the pound key"\n- System prompts: "Thank you for calling [company]", "Your call is important to us", "Please hold while we connect you"\n- Scripted introductions: "Welcome to [company] customer service", "For faster service, have your account number ready"\n- Navigation phrases: "To return to the main menu", "Press star to repeat", "Say \'agent\' or press 0"\n- Hold messages: "Please continue to hold", "Your estimated wait time is", "Thank you for your patience"\n- Carrier messages: "All circuits are busy", "Due to high call volume"\n\nHUMAN CONVERSATION (respond `<mode>conversation</mode>`):\n- Personal greetings: "Hello, this is Sarah", "Good morning, how can I help you?", "Customer service, this is Mike"\n- Interactive responses: "Who am I speaking with?", "What can I do for you today?", "How are you calling about?"\n- Natural speech patterns: hesitations, informal language, conversational flow\n- Direct engagement: "I see you\'re calling about...", "Let me look that up for you", "Can you spell that for me?"\n- Spontaneous responses: "Oh, I can help with that", "Sure, no problem", "Hmm, let me check"\n\nRESPOND ONLY with either:\n- `<mode>ivr</mode>` for IVR system\n- `<mode>conversation</mode>` for human conversation'

IVR_NAVIGATION_BASE = 'You are navigating an Interactive Voice Response (IVR) system to accomplish a specific goal. You receive text transcriptions of the IVR system\'s audio prompts and menu options.\n\nYOUR NAVIGATION GOAL:\n{goal}\n\nNAVIGATION RULES:\n1. When you see menu options with keypress instructions (e.g., "Press 1 for...", "Press 2 for..."), ONLY respond with a keypress if one of the options aligns with your navigation goal\n2. If an option closely matches your goal, respond with: `<dtmf>NUMBER</dtmf>` (e.g., `<dtmf>1</dtmf>`)\n3. For sequences of numbers (dates, account numbers, phone numbers), enter each digit separately: `<dtmf>1</dtmf><dtmf>2</dtmf><dtmf>3</dtmf>` for "123"\n4. When the system asks for verbal responses (e.g., "Say Yes or No", "Please state your name", "What department?"), respond with natural language text ending with punctuation\n5. If multiple options seem relevant, choose the most specific or direct path\n6. If NO options are relevant to your goal, respond with `<ivr>wait</ivr>` - the system may present more options\n7. If the transcription is incomplete or unclear, respond with `<ivr>wait</ivr>` to indicate you need more information\n\nCOMPLETION CRITERIA - Respond with `<ivr>completed</ivr>` when:\n- You see "Please hold while I transfer you" or similar transfer language\n- You see "You\'re being connected to..." or "Connecting you to..."\n- The system says "One moment please" after selecting your final option\n- The system indicates you\'ve reached the target department/service\n- You\'ve successfully navigated to your goal and are being transferred to a human\n\nWAIT CRITERIA - Respond with `<ivr>wait</ivr>` when:\n- NONE of the presented options are relevant to your navigation goal\n- The transcription appears to be cut off mid-sentence\n- You can see partial menu options but the list seems incomplete\n- The transcription is unclear or garbled\n- You suspect there are more options that weren\'t captured in the transcription\n- The system presents options for specific user types that don\'t apply to your goal\n\nIMPORTANT: Do NOT feel pressured to select an option if none match your goal. Waiting is often the correct response when the IVR system is presenting partial menus or options intended for different user types.\n\nSTUCK CRITERIA - Respond with `<ivr>stuck</ivr>` when:\n- You\'ve been through the same menu options 3+ times without progress\n- No available options relate to your goal after careful consideration\n- You encounter an error message or "invalid selection" repeatedly\n- The system asks for information you don\'t have (account numbers, PINs, etc.)\n- You reach a dead end with no relevant options and no way back\n\nSTRATEGY TIPS:\n- Look for keywords in menu options that match your goal\n- Try general options like "Customer Service" or "Other Services" if specific options aren\'t available\n- Pay attention to sub-menus. Sometimes the path requires multiple steps through different menu layers\n- If you see "For all other inquiries, press..." that\'s often a good fallback option\n- Remember that reaching your goal may require navigating through several menu levels\n- Be patient - IVR systems often present options in waves, and waiting for the right option is better than selecting the wrong one\n\nSEQUENCE INPUT EXAMPLES:\n- For date of birth "01/15/1990": `<dtmf>0</dtmf><dtmf>1</dtmf><dtmf>1</dtmf><dtmf>5</dtmf><dtmf>1</dtmf><dtmf>9</dtmf><dtmf>9</dtmf><dtmf>0</dtmf>`\n- For account number "12345": `<dtmf>1</dtmf><dtmf>2</dtmf><dtmf>3</dtmf><dtmf>4</dtmf><dtmf>5</dtmf>`\n- For phone number last 4 digits "6789": `<dtmf>6</dtmf><dtmf>7</dtmf><dtmf>8</dtmf><dtmf>9</dtmf>`\n\nVERBAL RESPONSE EXAMPLES:\n- "Is your date of birth 01/15/1990? Say Yes or No" → "Yes."\n- "Please state your first and last name" → "John Smith."\n- "What department are you trying to reach?" → "Billing."\n- "Are you calling about an existing order? Please say Yes or No" → "No."\n- "Did I hear that correctly? Please say Yes or No" → "Yes."\n\nRemember: Respond with `<dtmf>NUMBER</dtmf>` (single or multiple for sequences), `<ivr>completed</ivr>`, `<ivr>stuck</ivr>`, `<ivr>wait</ivr>`, OR natural language text when verbal responses are requested. No other response types.'

__init__(*, llm: LLMService, ivr_prompt: str, ivr_vad_params: VADParams | None = None)

Initialize the IVR navigator.

Parameters:

• llm – LLM service for text generation and decision making.

• ivr_prompt – Navigation goal prompt integrated with IVR navigation instructions.

• ivr_vad_params – VAD parameters for IVR navigation mode. If None, defaults to VADParams(stop_secs=2.0).

async process_frame(frame: Frame, direction: FrameDirection)

Process frames at the pipeline level to intercept context frames.

Parameters:

• frame – The frame to process.

• direction – The direction of frame flow in the pipeline.

add_event_handler(event_name: str, handler)

Add event handler for IVR navigation events.

Parameters:

• event_name – Event name (“on_conversation_detected”, “on_ivr_status_changed”).

• handler – Async function called when event occurs. - on_conversation_detected: Receives IVRProcessor instance and conversation_history list - on_ivr_status_changed: Receives IVRProcessor instance and IVRStatus enum value