VMware ESXi and vSphere Cluster Management

Asterisk Background Application: Interruptible Prompts and DTMF Menus

Learn how Asterisk Background() plays interruptible prompts, accepts DTMF menu choices, matches extensions, and handles invalid input and timeouts.

Background() is an Asterisk dialplan application for building interactive voice menus. It plays one or more sound prompts while listening for caller keypad input. When the caller enters a digit that matches an extension in the active dialplan context, Asterisk interrupts the prompt and begins executing that extension.

This makes Background() a central building block for IVR systems and auto attendants. An IVR, or Interactive Voice Response system, uses spoken prompts and keypad choices to serve or route callers. An auto attendant is a voice menu that directs callers to destinations such as sales, marketing, queues, voicemail, or internal extensions.

How Background() Works

DTMF means Dual-Tone Multi-Frequency signaling: the tones produced when a caller presses telephone keypad keys. During Background(), Asterisk listens for these tones while the sound prompt is playing.

1. The call enters a dialplan context and extension.
2. The dialplan answers the channel, if necessary.
3. Background() begins playing the prompt.
4. The caller presses a digit while the prompt is playing.
5. Asterisk checks whether the entered digit or extension exists in the active context.
6. If it matches, playback stops and execution starts at priority 1 of the selected extension.

A caller may enter a single digit such as 2. Multi-digit input can also be used when the dialplan supports multi-digit extensions and provides suitable digit collection behavior.

Background() Versus Playback()

Playback() is intended to play audio as a normal dialplan step. It does not provide the usual interruptible menu-selection behavior of Background(). Use Playback() for an announcement that should generally finish before the next dialplan instruction runs.

Use Background() when the prompt offers choices and callers should be able to select one before the recording finishes.

Dialplan Matching and Contexts

The dialplan is Asterisk call-processing logic organized into contexts, extensions, and priorities. A context is a named group of extensions. An extension is a dialplan entry selected by a dialed number or caller input. A priority is the ordered execution position inside an extension.

For Background() to route a digit, the digit must correspond to a valid extension in the relevant active context. For example, if the caller is running the menu in [menu-demo], the option extension 1 must be defined in that context unless the dialplan explicitly changes routing with an application such as Goto(). Execution of the selected option starts at priority 1.

The menu entry, its option extensions, and their destination logic therefore need to be designed together. A prompt that says “press 2 for sales” must have a working extension 2 available from the menu context.

Building a Basic Menu Context

A normal menu flow answers the channel, plays an interruptible greeting, provides additional time for input if needed, and defines the selectable options. The following five-option example uses extension 500 as the menu entry.

[menu-demo]
exten => 500,1,Answer()
 same => n,Background(welcome)
 same => n,WaitExten(10)

exten => 1,1,Playback(digits/1)
 same => n,Hangup()
exten => 2,1,Playback(digits/2)
 same => n,Hangup()
exten => 3,1,Playback(digits/3)
 same => n,Hangup()
exten => 4,1,Playback(digits/4)
 same => n,Hangup()
exten => 5,1,Playback(digits/5)
 same => n,Hangup()

Here, a caller can press 1 through 5 while welcome is playing. If no digit is entered during playback, the dialplan reaches WaitExten(10), which supplies a further collection period.

What Each Part Does

• Answer() answers the incoming channel before the menu is presented.
• Background(welcome) plays the sound-file basename welcome and listens for DTMF.
• WaitExten(10) waits up to ten seconds after the prompt completes for an extension to be entered.
• Extensions 1 through 5 implement the menu choices.
• Playback(digits/1), for example, plays a confirmation or demonstration announcement.
• Hangup() ends branches whose work is complete.

WaitExten() and Post-Prompt Input

WaitExten() provides a post-prompt collection period. It is distinct from the input period that exists while Background() is playing.

• During Background(), a matching digit can immediately interrupt the prompt and select an extension.
• After Background() completes, WaitExten() keeps the call waiting for more input.
• The argument is the timeout in seconds. For example, WaitExten(10) allows up to ten additional seconds.
• If the caller enters a valid extension during this period, Asterisk transfers execution to that extension at priority 1.
• If the caller does not enter a valid extension before the wait expires, the special t extension can handle the timeout.

Choose a timeout that gives callers enough time to understand the prompt and press a key. A short timeout can make a working menu feel unreliable.

Implementing Menu Options

Each option extension can perform different work. It can play a confirmation, invoke another menu, transfer to a destination, send the call to a queue, dial a phone or trunk, or terminate the call.

Department Routing Example

Suppose the greeting says, “Press 2 for sales. Press 3 for marketing.” The prompt wording and dialplan must use the same mapping.

[main-menu]
exten => 500,1,Answer()
 same => n,Background(custom/main-menu)
 same => n,WaitExten(10)

exten => 2,1,Goto(sales-menu,s,1)
exten => 3,1,Goto(marketing-menu,s,1)

Invalid Input and Timeout Handling

Asterisk provides special extensions for common menu failures:

• i extension: handles invalid input, such as a digit that does not match a valid menu option.
• t extension: handles a timeout when the caller does not enter an extension before WaitExten() expires.

A basic recovery pattern informs the caller and returns to the menu.

exten => i,1,Playback(pbx-invalid)
 same => n,Goto(500,1)

exten => t,1,Playback(vm-goodbye)
 same => n,Hangup()

Returning to the menu from i is useful for short demonstrations, but a production menu should limit retries. Otherwise, a caller who repeatedly presses an invalid key can be trapped in an endless loop. Track an attempt counter and, after a defined limit, route the caller to an operator, voicemail, another menu, or Hangup().

Menu Input Outcomes

Call Completion and Hangup Behavior

Use Hangup() after a terminal confirmation or announcement when the menu branch has finished its work. In the five-option example, each digit announcement is followed by Hangup().

A branch that transfers the caller, enters a queue, or starts another call-processing application may not need an immediate Hangup() in the menu branch. The next application controls what happens to the call.

The special h extension is also relevant when cleanup must run after the caller hangs up. It can be used for tasks such as recording final state, releasing resources, or writing call details, depending on the deployment.

Sound Prompt Requirements

Background() normally references an Asterisk sound-file basename, not a complete filename with an extension. For example, Background(welcome) refers to a prompt named welcome, while Background(custom/main-menu) refers to a prompt below the custom sound directory.

• Install the audio file in an Asterisk-recognized sounds directory.
• Use a supported audio format available in the deployment.
• Reference the correct path relative to the sounds directory.
• Record the choices clearly and state exactly which key callers should press.
• Keep the spoken choices consistent with the configured extensions.

A useful prompt might say, “Press 2 for sales, or press 3 for marketing.” Avoid announcing options that are missing or mapped to a different destination.

Deploying and Testing the Dialplan

Edit extensions.conf or the dialplan source used by your deployment. After saving changes, reload the dialplan from the Asterisk CLI:

asterisk -rvvv
dialplan reload

To inspect the menu extension and increase console detail while testing, use:

dialplan show 500@menu-demo
core set verbose 3

1. Call the menu extension, such as 500.
2. Confirm that the channel is answered and the greeting plays.
3. Press a valid digit while the greeting is playing.
4. Call again and press a valid digit after the greeting during WaitExten().
5. Press an invalid digit and verify that the i branch runs.
6. Make no selection and verify that WaitExten() expires and the t branch runs.
7. Confirm that each option reaches the intended destination and that terminal branches end correctly.

Use the Asterisk CLI to verify the active context, selected extension, and priorities. The command dialplan show 500@menu-demo is especially useful when a menu appears to be loaded but input does not route as expected.

Troubleshooting Common Problems

The Prompt Plays but Key Presses Do Not Route

• Verify that the selected digit exists in the current context.
• Confirm that the option extension begins at priority 1.
• Check that the inbound route placed the call in the expected context.
• Review endpoint DTMF settings and confirm that the calling device is delivering keypad signaling.
• Use dialplan show and CLI verbosity to confirm that the loaded dialplan matches the edited source.

Input Works Only After the Greeting

This commonly means Playback() was used instead of Background(). Replace the prompt step with Background(), reload the dialplan, and confirm the running extension in the CLI.

The Caller Does Not Have Enough Time

Add WaitExten() after Background(), or increase its interval. Also define a t extension so timeout behavior is explicit and predictable.

A Valid-Looking Choice Is Rejected

Check that the digit is defined in the active context, not only in another context. Align the prompt, option extensions, and any Goto() destinations after every menu change.

A Custom Greeting Cannot Be Found

Verify the file location, basename, relative path, and supported audio format. A missing sound file or incorrect basename can make the menu appear to skip its prompt.

Callers Loop Forever on Invalid Input

An i handler that always returns to the menu needs a retry limit. Track attempts and route repeated failures to an operator, voicemail, or Hangup(). Improve the prompt if callers cannot identify the valid choices.

Exam-Relevant Notes

• Background() is interruptible by caller DTMF; Playback() is normally used for non-interactive playback.
• A matching digit selects an extension in the active context and begins at priority 1.
• WaitExten() supplies additional post-prompt time; it is not the same as digit collection during Background().
• The i extension handles invalid input, while t handles an extension-wait timeout.
• Menu prompts, option mappings, and context placement must agree.
• Use Hangup() for terminal branches, and consider the h extension for post-hangup cleanup.

For a focused reference to this application, see The Background Application.