Capturing key presses with agi-dtmf.agi

DTMF — Dual-Tone Multi-Frequency — is the system of audio tones that a telephone keypad generates when you press a digit. When VICIdial needs to pass key presses to a downstream IVR, navigate an automated phone tree, or send account codes to a carrier, it uses agi-dtmf.agi to play those tones from within the Dialplan. The script reads the sequence to send from the callerid field on the channel and plays the corresponding DTMF sound files.

This is different from capturing a caller's key press in an IVR (interactive voice response) context — this script sends DTMF outbound, from Asterisk to another system. The typical use is an outbound call that needs to navigate through a third-party phone menu before reaching a human, or pass a PIN to an external service, without any live agent on the line.

How the script processes the DTMF sequence

flowchart TD
  A[Dialplan sets callerid to DTMF sequence] --> B[Answer and Playback silence]
  B --> C[AGI agi-dtmf.agi called]
  C --> D{Read callerid field}
  D --> E{Each character}
  E -->|digit 0-9 * #| F[Play matching DTMF sound file]
  E -->|letter A-Z| G[Translate to dialpad digit]
  G --> F
  E -->|comma| H[Pause 1 second]
  H --> E
  F --> E
  E -->|end of string| I[Hangup]

The accepted characters are: digits 0 through 9, hash (#), star (*), and comma (,). A comma means pause for one second. Letters are translated to their dialpad equivalents — the same mapping you see on a telephone keypad. For example, the word SMITH would become 76484 before the tones are played. This is useful when a destination system uses word-based account codes that were originally designed for keypad entry.

DTMF sound files must be present in /var/lib/asterisk/sounds for the script to play them. If a file for a specific digit is missing, that tone will be skipped silently.

Dialplan setup and the signalonly option

The script takes one optional argument: signalonly. In standard mode the script plays audio files that represent DTMF tones. In signalonly mode it sends actual in-band DTMF signals rather than playing recorded tone files. Use signalonly when the destination system uses real DTMF detection rather than audio playback matching. The difference matters for DTMF muting: some trunks suppress in-band DTMF, so you should test both modes against your actual carrier if you see dropped digits.

; Standard audio DTMF playback
exten => 8500998,1,Answer
exten => 8500998,2,Playback(silence)
exten => 8500998,3,AGI(agi-dtmf.agi)
exten => 8500998,4,Hangup

; Signal-only DTMF
exten => 8500998,3,AGI(agi-dtmf.agi,signalonly)

Notice the Playback(silence) step before the AGI call. This gives the remote end a moment to settle after answer before it receives DTMF — without it, the first tone in the sequence can be cut off if the remote IVR has not finished its own setup.

When to use this versus other DTMF approaches

This script is for automated DTMF sending without an Agent on the call. If you have a live agent who needs to send DTMF to a carrier mid-call — for example, to navigate a bank IVR during a sales call — VICIdial's agent screen has its own DTMF controls. For recording what a caller presses in an inbound IVR context, see the verification IVR script. The distinction matters because DTMF muting behaves differently depending on whether the tone is being sent or received.

The Extension numbering used for the DTMF script context (like 8500998 in the example) is arbitrary — match it to your own dial plan layout. For more on how AGI and API tools work together in the VICIdial stack, see the VICIdial API and AGI overview. For reading how API responses map to call outcomes, the API response guide is a useful companion.

If you want a VICIdial box that is already configured and ready to extend with custom dialplan entries, every VICIfast plan provisions one in under 40 seconds.