IVR Navigation

Overview

Vapi offers the DTMF tool to enable your assistants to navigate IVR menus and press keys to enter values (for example, member IDs, account numbers, and dates).

IVR systems can be sensitive to timing and formatting; this guide explains common challenges and provides practical recommendations to make IVR navigation reliable.

Recommendations

1. Add short pauses between keys

Some IVRs buffer audio or expect keys at a slower pace. Sending keys too quickly (for example, 123456#) can cause missed or misread inputs. Prompt your assistant to insert brief pauses between keys, so it has better chances of success, as it gives the IVR more time to register each tone.

Provider-specific pause characters

• Twilio and Telnyx: Use w for a 0.5s pause, W for a 1s pause. Example: 1w2w3W4#
• Vapi numbers, BYO SIP trunks, and Vonage: Pause characters aren’t supported. On Vapi numbers, the keys play back to back. If an IVR needs time between entries, send each entry after the prompt that asks for it.

Start with 0.5s pauses and increase only if keys are still missed. For full provider support, see Where keypad tones work.

2. Give menus time to finish before responding

IVR menus often speak slowly and include longer silences than typical user speech. If your assistant responds too quickly, it may send tones before the IVR has finished listing options and there’s a chance that is not ready to receive inputs.

• Wait for all options to be spoken before sending the first DTMF sequence.
• Stay silent while waiting by replying with a single space character (” ”) so nothing is spoken.
• Avoid overlapping speech with IVR audio; prioritize listening until the option is clear.

Prompt Example

[When navigating an IVR tree]
  - WAIT for all options to be spoken before proceeding
  - Once you have heard all options, use the dtmf tool with an input key that matches the option you want to select
  - Avoid saying anything if using the dtmf tool at the same time
[When waiting]
  - Reply with an empty string like " " to ensure nothing is spoken
[Call Flow]
  1. Navigate IVR tree (if needed)
    - In order to get connected with a live representative that can handle your request, you may need to navigate an IVR tree.
    - This might sound like "Press 1 for..."
    - Look for options that indicate operator assistance
    - As soon as you get connected to a human, proceed to the next step

LiveKit Smart Endpointing

Use a startSpeakingPlan that allows slower cadence at the beginning of calls (commonly when interacting with IVRs) and faster cadence once a human answers.

{
  "startSpeakingPlan": {
    "smartEndpointingPlan": {
      "provider": "livekit",
      "waitFunction": "t < 30 ? (x * 500 + 300) : (20 + 500 * sqrt(x) + 2500 * x^3)"
    }
  }
}

3. Retry with progressively slower inputs or spoken fallback

Some IVRs accept inputs more reliably on a second attempt or when keys arrive more slowly. If keys fail, retry with increased spacing; if tones still fail, speak the option out loud as a fallback.

Examples:

1st try  →  123#           (fast)
2nd try  →  1w2w3#         (medium; 0.5s gaps)
3rd try  →  1W2W3#         (slow; 1s gaps)

User: For Sales press 1 or say "Sales"
Assistant: dtmf(keys=1)
User: For Sales press 1 or say "Sales"
Assistant: dtmf(keys=w1)
User: For Sales press 1 or say "Sales"
Assistant: Sales

4. Compare telephony transports for your target IVRs

DTMF sending varies across telephony providers due to internal implementations. For the phone numbers and IVRs you target, test multiple transports and choose the most reliable for your use case.

• Try and compare: Twilio, Telnyx, Vonage, Vapi numbers, and BYO SIP trunks
• Evaluate: key recognition accuracy, latency between keys, and success rate across menu depths.

5. Enter multiple keypad entries at once

Some IVRs ask for several keys or letters in a single prompt (for example, by‑name directories that require the first three letters of a last name). In these cases, send all required keys in a single dtmf call, using pause characters between keys so the IVR reliably registers them.

• How: Use keys with a combined sequence. On Twilio and Telnyx, insert w (0.5s pause) or W (1s pause) between entries.
• Why: Multiple separate dtmf calls can arrive too slowly or be partially ignored; a single combined sequence is more consistent.

{
  "role": "tool_calls",
  "time": 1760710106938,
  "message": "",
  "toolCalls": [
    {
      "id": "call_CTgHfSj4lNZaqVjByk2eJooc",
      "type": "function",
      "function": {
        "name": "dtmf",
        "arguments": "{\"keys\": \"w2w1w2\"}"
      }
    }
  ],
  "secondsFromStart": 25.16
}

# If the IVR says: "Enter the first 3 letters of the last name"
# Map letters to keys using the IVR's on‑screen or spoken mapping (e.g., S=7, M=6, I=4)
dtmf(keys=w7w6w4)