Asterisk course

Using the Asterisk Background Application for Interactive Voice Menus

Learn how Asterisk Background() plays prompts while accepting DTMF input, using WaitExten(), and routing callers through an IVR or auto attendant.

Background() is an Asterisk dialplan application for playing audio while listening for caller keypad input. It is a central building block for interactive voice response (IVR) systems, auto attendants, and self-service telephone menus.

This lesson assumes that you understand basic contexts, extensions, priorities, and the same => n notation in extensions.conf. For background concepts, see What Is a Dialplan, Contexts, Extensions, and Priorities.

What Background() Does

The Background() application plays one or more sound prompts to the caller. While the prompt is playing, Asterisk monitors the caller's keypad for DTMF, or dual-tone multi-frequency signaling. DTMF tones are the signals generated when a caller presses telephone keypad buttons.

When the caller enters digits that form a valid extension in the current dialplan context, Asterisk can stop the prompt and transfer execution to that extension's first priority. This makes Background() suitable for menus such as:

  • Press 1 for Sales.
  • Press 2 for Support.
  • Press 3 to hear business hours.
  • Press 0 for an operator.

An IVR is an interactive voice response system that lets callers navigate services with prompts and keypad input. An auto attendant is an automated telephone menu that directs callers to departments, extensions, or services. Both commonly use Background().

Background() Versus Playback()

Playback() plays an audio file as a non-interactive prompt. Background() also plays audio, but it listens for DTMF and can use matching dialplan extensions for immediate menu routing.

Application — Plays audio — Accepts menu DTMF during playback — Typical use

Background() — Yes — Yes; a valid digit sequence can interrupt playback — IVR menus and auto attendants

Playback() — Yes — No immediate menu routing from digits entered during playback — Informational or non-interruptible announcements

Use Background() when callers should be able to choose an option while the menu prompt is playing. Use Playback() when the complete message should be heard before the dialplan proceeds, such as a short legal notice, a status announcement, or an instruction that should not be interrupted.

For more detail about the non-interactive application, see The Playback Application.

How DTMF Selects a Dialplan Destination

A dialplan is Asterisk's call-routing logic, commonly stored in extensions.conf. An extension is a numbered or patterned destination containing one or more ordered priorities. A context is a named group of extensions that controls which destinations are available to a call.

When Background() receives digits, Asterisk checks whether those digits match an available extension in the current context. If the entered value is a valid match, prompt playback stops and execution transfers to that extension's first priority.

For example, if the caller presses 3 while the call is in the ivr-menu context, an extension such as exten => 3,1,... must exist in that context. Merely mentioning “press 3” in the recording does not create a route. The prompt and dialplan must use the same menu map.

Caller input — Dialplan extension — Destination action — Example business destination

1 — exten => 1,1,... — Execute the priority-one application — Sales queue

2 — exten => 2,1,... — Execute the priority-one application — Support queue

3 — exten => 3,1,... — Execute the priority-one application — Business-hours announcement

0 — exten => 0,1,... — Execute the priority-one application — Receptionist

Basic IVR Call Flow

  1. Answer the incoming call.
  2. Play a welcome or menu prompt with Background().
  3. Allow a caller to select a destination during the prompt.
  4. Use WaitExten() after the prompt to allow additional input.
  5. Route each valid choice to a department, announcement, queue, voicemail box, extension, or other treatment.

The call must be answered before interactive audio and input collection begin. The Answer application provides that first step.

Background() Syntax and Sound Prompts

The basic form is:

Background(sound-file)

Sound file names are normally written without a filename extension. For example:

same => n,Background(welcome)

Asterisk searches its configured sounds directories and language-specific sound paths for the requested prompt. The exact directory depends on the installation and sound-file configuration. A language setting can cause Asterisk to prefer a language-specific version when one is available.

welcome can be a custom recording such as: “Welcome to Example Company. Press 1 for Sales, 2 for Support, 3 for hours, 4 for voicemail, or 5 for the operator.” The recording must clearly state which digits map to which destinations. If callers cannot understand the choices, even a technically correct dialplan will be difficult to use.

Custom prompts must use a basename that matches the reference in the dialplan, be stored in a sounds path Asterisk can access, and use an audio format supported by the installation and channel.

WaitExten() and the Post-Prompt Input Period

Background() listens for matching input while its audio is playing. After the prompt finishes, WaitExten(timeout) waits for additional digit entry for the specified number of seconds.

same => n,WaitExten(10)

In this example, Asterisk waits up to 10 seconds after the prompt completes. The timeout is a caller-experience decision, not an arbitrary constant. A short timeout keeps the menu moving but may frustrate callers who need time to find a key. A longer timeout is more forgiving but can make silence feel unresponsive.

The distinction is important:

  • Digits entered while Background() is playing can interrupt the prompt as soon as they form a valid extension.
  • Digits entered during WaitExten() are collected after playback has finished.
  • If no usable digit is entered before the wait expires, Asterisk follows the special t extension when one is defined.

See Invalid Entries And Timeouts for related dialplan behavior.

Five-Choice Test Menu

The following example answers extension 500, plays a custom welcome prompt, waits for input, and provides five simple test destinations. Each destination plays a digit recording so the menu can be tested without configuring queues or real departments.

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

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

When a caller dials 500, Asterisk answers the call and begins Background(welcome). Pressing 1 through 5 during the greeting transfers execution to the matching extension. If the caller waits until the greeting ends, WaitExten(10) provides another 10 seconds to enter a choice.

In production, replace the test Playback() actions with the desired call treatment. For example, a choice can use Dial() for an extension or ring group, send a caller to a queue, play an announcement, or transfer to voicemail. See The Dial Application and Defining The Queues.

Invalid Entries and Timeouts

Callers may press a digit that is not offered, enter an incomplete sequence, or provide no input. Asterisk provides special extensions for these outcomes:

  • i extension: Handles invalid input, such as an unsupported digit.
  • t extension: Handles a timeout when the caller does not enter a usable choice within the available time.

A simple retry pattern informs the caller and returns to extension 500:

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

exten => t,1,Playback(vm-nobodyavail)
 same => n,Goto(500,1)

This example can loop forever. A production menu should count attempts and provide a fallback after a reasonable limit, such as transferring to a receptionist, offering voicemail, or ending the call. A retry counter can be implemented with channel variables and conditional dialplan logic.

Caller behavior — Dialplan handler — Recommended response

Unsupported digit — i — Explain the valid choices and replay the menu

No digit before the wait expires — t — Replay the menu or offer an operator

Repeated invalid choices — Attempt-count logic — Transfer to assistance or voicemail

Valid digit — Matching numeric extension — Route to the selected destination

Department-Routing Example

A department menu might announce Sales on 2 and Marketing on 3. The prompt wording, available extensions, and destination actions must agree:

[company-ivr]
exten => 500,1,Answer()
 same => n,Background(company-menu)
 same => n,WaitExten(8)

; Press 2 for Sales
exten => 2,1,Dial(PJSIP/sales-ring-group)

; Press 3 for Marketing
exten => 3,1,Dial(PJSIP/marketing-ring-group)

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

exten => t,1,Playback(vm-nobodyavail)
 same => n,Goto(500,1)

The destination names in this illustrative example must correspond to real endpoint or routing configuration in the system. A production design might instead send 2 or 3 to a queue, ring group, direct extension, or another context. Keep the menu routes in the intended context so callers cannot reach unintended destinations.

Reloading and Testing

After changing the dialplan, load the new configuration before placing a test call:

dialplan reload

At the Asterisk CLI, confirm that the reload completes without configuration errors. Then test the menu extension from a permitted phone or trunk:

  1. Call extension 500 in the correct context.
  2. Confirm that the call is answered and the welcome prompt plays.
  3. Press each permitted digit from 1 through 5 while the prompt is still playing.
  4. Repeat each choice after the prompt finishes, during the WaitExten() period.
  5. Press an unsupported digit and verify the i path.
  6. Enter no digit and verify the t path.
  7. Test repeated invalid and timeout attempts to confirm the fallback limit.

Testing both early and late input is important. A menu that works only after the prompt ends may be using Playback() or may not have matching extensions available when Background() is running.

Operational Considerations

  • Ensure phones, SIP devices, and trunks send DTMF using a mode Asterisk can detect. Review the endpoint's SIP or PJSIP DTMF configuration when digits are missing or incorrect.
  • Avoid ambiguous menu extensions and overlapping digit patterns that can delay routing while Asterisk waits to determine whether more digits will arrive.
  • Use concise prompts. Let callers interrupt the prompt when doing so improves the experience.
  • Keep the numeric choices, context, and destination logic aligned. A digit advertised by the recording must have a matching extension in the appropriate context.
  • Use clear, accessible language and avoid presenting too many choices at once.
  • Provide a human-assistance path, such as 0 for an operator, when the business process permits it.
  • Verify custom prompt ownership, permissions, location, basename, and audio format if a greeting cannot be played.

Troubleshooting

The greeting plays but digits do not route

  • Confirm that the selected digit has a matching extension and first priority.
  • Verify that the call entered the context containing the menu extensions.
  • Check endpoint or trunk DTMF delivery and test from more than one device.

Digits work only after the greeting

  • Check whether Playback() was used instead of Background().
  • Confirm that valid menu extensions are available in the active context while the prompt plays.

Every selection is treated as invalid

  • Compare the advertised choices with the numeric extensions.
  • Add the missing extension or correct the prompt.
  • Review DTMF events in the Asterisk console for unexpected digits or signaling problems.

The call follows an unexpected path after silence

  • Define a t extension in the menu context.
  • Confirm that WaitExten() is present when post-prompt input is expected.
  • Choose an explicit timeout destination rather than allowing the call to end unexpectedly.

The custom greeting cannot be played

  • Verify the file's location and basename. The dialplan normally references the name without its extension.
  • Check that the Asterisk process can read the file.
  • Use an audio format supported by the installation and channel.

Key Points

  • Background(sound-file) plays a prompt while listening for DTMF.
  • A valid digit sequence must match an extension in the current context.
  • A matching extension interrupts the prompt and starts at that extension's first priority.
  • WaitExten(timeout) provides an additional input period after playback ends.
  • The i extension handles invalid input, while t handles timeout.
  • Use Playback() for prompts that should not provide interactive routing during playback.
  • Always test valid choices during and after the prompt, invalid entries, timeouts, DTMF delivery, and fallback behavior.