Build an IVR menu

VoiceIVR menu (DTMF)

Play a menu, collect keypad input, and route the caller to the right place.

Also called phone menu, auto attendant, press 1 menu

dtmf

The claim

A complete phone menu is one SWML document: prompt collects a digit, switch branches on it, and each branch is a named section. Nothing here needs a server: host the YAML as a SWML Script in the Dashboard and point a number at it.

Why it holds

The Python surface builds the identical document with SWMLService. Destinations come from the environment, and every verb is validated against the SWML schema before it is served.

How it works

- prompt:
    play: "say:Thanks for calling. Press 1 for sales, 2 for support, or 3 for opening hours."
    max_digits: 1
- switch:
    variable: prompt_value
    case:
      "1": [ { transfer: { dest: sales } } ]
      "2": [ { transfer: { dest: support } } ]
      "3": [ { transfer: { dest: hours } } ]
    default: [ { play: { url: "say:Sorry, I did not catch that." } }, { transfer: { dest: main } } ]

prompt stores the digit in prompt_value. switch matches it and transfer jumps to a section of the same document. The sales and support sections connect to a phone number; hours plays a message and hangs up. An unrecognised key re-prompts by transferring back to main.

What to change first

Add a fourth option that transfers to a SIP address instead of a number. Alternatively, collect speech with speech_hints and branch on what the caller says. See collect-speech-input-and-branch.

Where this sits

Before this

Answer an inbound call

Collect speech input and branch on it

Queue a call until an agent is free Transfer a call

python/app.py

"""Build an IVR menu.

The same document as swml/agent.yaml, built in Python so the destinations come
from the environment and every verb is validated against the SWML schema before
it is served.

Written against signalwire-sdk 3.0.1 (SWMLService).
"""
import os

from dotenv import load_dotenv
from signalwire import SWMLService

# the SDK does not read .env for you
load_dotenv()

SALES = os.getenv("SALES_NUMBER", "+15550100001")
SUPPORT = os.getenv("SUPPORT_NUMBER", "+15550100002")
HOURS = "We are open Monday to Friday, nine to five, Eastern time."

MENU = {
    "1": ("sales", "Connecting you to sales.", SALES),
    "2": ("support", "Connecting you to support.", SUPPORT),
}


def build(service=None):
    """Populate a SWMLService with the menu. Returns the service."""
    service = service or SWMLService(name="ivr", route="/ivr")
    service.reset_document()

    service.add_verb("answer", {})
    service.add_verb("prompt", {
        "play": "say:Thanks for calling. Press 1 for sales, 2 for support, "
                "or 3 for opening hours.",
        "max_digits": 1,
        "digit_timeout": 6,
        "initial_timeout": 8,
    })
    cases = {digit: [{"transfer": {"dest": section}}]
             for digit, (section, _, _) in MENU.items()}
    cases["3"] = [{"transfer": {"dest": "hours"}}]
    service.add_verb("switch", {
        "variable": "prompt_value",
        "case": cases,
        "default": [
            {"play": {"url": "say:Sorry, I did not catch that."}},
            {"transfer": {"dest": "main"}},
        ],
    })

    for section, announce, number in MENU.values():
        service.add_section(section)
        service.add_verb_to_section(section, "play", {"url": f"say:{announce}"})
        service.add_verb_to_section(section, "connect", {"to": number})
        service.add_verb_to_section(section, "hangup", {})

    service.add_section("hours")
    service.add_verb_to_section("hours", "play", {"url": f"say:{HOURS}"})
    service.add_verb_to_section("hours", "hangup", {})
    return service


if __name__ == "__main__":
    build().serve(port=int(os.getenv("PORT", "8080")))

# Build an IVR menu - one SWML document, no server.
# Host this as a SWML Script in the Dashboard and point a number at it, or serve
# it from any URL. Replace the two phone numbers before you use it.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - prompt:
        play: >-
          say:Thanks for calling. Press 1 for sales, 2 for support,
          or 3 for opening hours.
        max_digits: 1
        digit_timeout: 6
        initial_timeout: 8
    - switch:
        variable: prompt_value
        case:
          "1":
            - transfer: { dest: sales }
          "2":
            - transfer: { dest: support }
          "3":
            - transfer: { dest: hours }
        default:
          - play: { url: "say:Sorry, I did not catch that." }
          - transfer: { dest: main }
  sales:
    - play: { url: "say:Connecting you to sales." }
    - connect: { to: "+15550100001" }
    - hangup: {}
  support:
    - play: { url: "say:Connecting you to support." }
    - connect: { to: "+15550100002" }
    - hangup: {}
  hours:
    - play: { url: "say:We are open Monday to Friday, nine to five, Eastern time." }
    - hangup: {}

Run it

Markup only: paste swml/agent.yaml into a new SWML Script in the Dashboard, assign a phone number to it, call the number.

Python:

cd python
pip install -r requirements.txt
SALES_NUMBER=+1555... SUPPORT_NUMBER=+1555... python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/ivr/.

Verify it

python verify.py          # from the recipe folder, not python/

Both surfaces are validated against the SDK’s bundled SWML schema. The verifier asserts:

one digit is collected
every case transfers to a section that exists
the default branch re-prompts

Report an issue