Background()

Since 13.8.0 Applications

Play an audio file while waiting for digits of an extension to go to.

Last reviewed 2026-04-14

BackGround(filenames[,options,langoverride,context])

Dialplan Builder -- build your BackGround() command

filename1

options (optional)

langoverride (optional)

Explicitly specifies which language to attempt to use for the requested sound files.

context (optional)

This is the dialplan context that this application will use when exiting to a dialed extension.

Full arguments reference

filenames required - Ampersand separated list of filenames. If the filename is a relative filename (it does not begin with a slash), it will be searched for in the Asterisk sounds directory. If the filename is able to be parsed as a URL, Asterisk will download the file and then begin playback on it. To include a literal & in the URL you can enclose the URL in single quotes.
- filename1 required
- filename2 (multiple)
options
- s - Causes the playback of the message to be skipped if the channel is not in the up state (i.e. it hasn't been answered yet). If this happens, the application will return immediately.
- n - Don't answer the channel before playing the files.
- m - Only break if a digit hit matches a one digit extension in the destination context.
- p - Do not allow playback to be interrupted with digits.
langoverride - Explicitly specifies which language to attempt to use for the requested sound files.
context - This is the dialplan context that this application will use when exiting to a dialed extension.

Description

This application will play the given list of files (do not put extension) while waiting for an extension to be dialed by the calling channel. To continue waiting for digits after this application has finished playing files, the WaitExten application should be used.

If one of the requested sound files does not exist, call processing will be terminated.

This application sets the following channel variable upon completion:

BACKGROUNDSTATUS - The status of the background attempt as a text string.
- SUCCESS
- FAILED

Arguments

filenames required - Ampersand separated list of filenames. If the filename is a relative filename (it does not begin with a slash), it will be searched for in the Asterisk sounds directory. If the filename is able to be parsed as a URL, Asterisk will download the file and then begin playback on it. To include a literal & in the URL you can enclose the URL in single quotes.
- filename1 required
- filename2 (multiple)
options
- s - Causes the playback of the message to be skipped if the channel is not in the up state (i.e. it hasn't been answered yet). If this happens, the application will return immediately.
- n - Don't answer the channel before playing the files.
- m - Only break if a digit hit matches a one digit extension in the destination context.
- p - Do not allow playback to be interrupted with digits.
langoverride - Explicitly specifies which language to attempt to use for the requested sound files.
context - This is the dialplan context that this application will use when exiting to a dialed extension.

User Notes

Know a tip or gotcha for this topic? Share it below and help others.

Contribute a note

Share a tip, gotcha, or practical example. Keep it under 2000 characters. No questions (use the Asterisk community forums for support). Wrap code in backticks.