Send DTMF to someone else's IVR

Voiceautomated DTMF navigation

Send programmed keypad tones during an outbound call to navigate an external IVR.

dtmf

The claim

A call that dials someone else’s phone tree and presses through it on its own. The keys travel in the same request that places the call, and the platform sends them once the far end answers.

Why it holds

There is an obvious way to send a digit that looks right and fires too late. The mechanism below is the one that lands while a menu is listening.

How it works

The obvious shape is connect to the tree and then send_digits. It does not work. connect owns the bridge until the far leg ends, so the next verb runs only once the IVR has hung up, and the digits go nowhere.

The dial command takes send_digits as a parameter instead. The spec describes it as digits to send *after the call is answered*, which is the moment a phone tree starts accepting input.

client.calling.dial(**{
    "from": FROM,
    "to": IVR,
    "send_digits": ",,,,,,2,,,1",   # wait, press 2, wait, press 1
    "swml": after_answer,           # what our side does once through
})

The pacing characters are not the ones the send_digits verb uses. Here the parameter allows 0-9, A-D, *, #, w for a wait and , for a pause; there is no capital W. A string written for the verb will not do here.

A menu that has not finished speaking has not started listening, so the pauses are the design. Six pauses of greeting, press 2, three of submenu, press 1.

Writing that by hand gives ",,,,,,2,,,1", which is unreadable and un-tunable, so the route stays as pairs and the string is built from it:

ROUTE = [(6, "2"), (3, "1")]

A menu that got slower is a number you change rather than a run of commas you count.

Limitations

This is open loop. Nothing checks that pressing 2 reached the menu you expected, so a tree that changes its greeting sends your call somewhere else silently. Closing the loop needs something listening to the far end, which is start-live-transcription and a good deal more machinery.

Pauses are fixed when the call is placed. A queue that answers in four seconds on Tuesday and forty on Monday cannot be paced by a constant.

What to change first

Drop the leading pauses to one and place the call. The digit lands during the greeting, the menu never registers it, and the call sits in the top-level tree.

Where this sits

Seen in a build

One of 7 recipes composed by IVR navigator: an AI agent that works through phone menus to reach a human.

python/app.py

"""Send DTMF to an external IVR.

The digits travel with the origination, not as a verb after `connect`.

`connect` owns the bridge until the far leg ends, so a `send_digits` placed
after it does not run until the IVR has already hung up. The `dial` command
takes a `send_digits` parameter instead, described as digits to send *after the
call is answered*, which is the moment a phone tree starts listening.

Its pacing characters differ from the `send_digits` verb: here `w` is a wait
and `,` is a pause, and there is no capital `W`.

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

from dotenv import load_dotenv
from signalwire.rest import RestClient

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

client = RestClient()

FROM = os.getenv("SIGNALWIRE_PHONE_NUMBER", "+15550001111")
IVR = os.getenv("IVR_NUMBER", "+15550100050")
PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")

# (pauses to wait before pressing, key). One `,` is the documented pause unit;
# how long the far end talks before it will accept input decides the count.
ROUTE = [(6, "2"), (3, "1")]

# Allowed by the dial parameter: 0-9, A-D, *, #, w (wait), `,` (pause).
ALLOWED = set("0123456789ABCD*#w,")


def digits_for(route):
    """Waits before each key, spelled the way the parameter spells them."""
    out = "".join("," * pauses + key for pauses, key in route)
    bad = set(out) - ALLOWED
    if bad:
        raise ValueError(f"not sendable as DTMF: {sorted(bad)}")
    return out


def navigate(after_answer):
    """Dial the tree, press through it, then run `after_answer`."""
    return client.calling.dial(**{
        "from": FROM,
        "to": IVR,
        # pressed once the far end answers, which is when a menu listens
        "send_digits": digits_for(ROUTE),
        # what the call does once it is through the tree
        "swml": after_answer,
        "status_url": f"{PUBLIC_URL}/call-status",
        "status_events": ["answered", "ended"],
    })


def hold_for_a_human():
    """The document that runs on our side once the digits are sent."""
    return {
        "version": "1.0.0",
        "sections": {
            "main": [
                {"answer": {}},
                # a human on the far end will eventually say something
                {"play": {"url": "silence:3600"}},
            ]
        },
    }


if __name__ == "__main__":
    print(navigate(hold_for_a_human()))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # add your credentials and IVR_NUMBER
python app.py

Verify it

No network, no account:

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

With the HTTP layer replaced by a recorder, navigate() must make one request. The verifier asserts:

the digits travel in the dial parameter, whose documented description says they are sent after the call is answered
every character is one that parameter allows, and no capital W appears
the string spells the route, pause for pause and key for key
it begins with a pause, since a route that presses immediately is the bug
the inline document is valid SWML and contains no send_digits verb, which after connect would fire once the bridge had already ended

Report an issue