SpeechBackground()

Since 1.6.1.0 Applications

Play a sound file and wait for speech to be recognized.

Last reviewed 2026-04-14

SpeechBackground(sound_file[,timeout,options])

Dialplan Builder -- build your SpeechBackground() command

sound_file

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.

timeout (optional)

Timeout integer in seconds. Note the timeout will only start once the sound file has stopped playing.

options

n: Don't answer the channel if it has not already been answered.

Don't answer the channel if it has not already been answered.

p: Return partial results when backend is terminated by timeout.

Return partial results when backend is terminated by timeout.

Full arguments reference

sound_file 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.
- sound_file required
- sound_file2 (multiple)
timeout - Timeout integer in seconds. Note the timeout will only start once the sound file has stopped playing.
options
- n - Don't answer the channel if it has not already been answered.
- p - Return partial results when backend is terminated by timeout.

Description

This application plays a sound file and waits for the person to speak. Once they start speaking playback of the file stops, and silence is heard. Once they stop talking the processing sound is played to indicate the speech recognition engine is working. Once results are available the application returns and results (score and text) are available using dialplan functions.

The first text and score are ${SPEECH_TEXT(0)} AND ${SPEECH_SCORE(0)} while the second are ${SPEECH_TEXT(1)} and ${SPEECH_SCORE(1)}.

The first argument is the sound file and the second is the timeout integer in seconds.

Hangs up the channel on failure. If this is not desired, use TryExec.

Arguments

sound_file 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.
- sound_file required
- sound_file2 (multiple)
timeout - Timeout integer in seconds. Note the timeout will only start once the sound file has stopped playing.
options
- n - Don't answer the channel if it has not already been answered.
- p - Return partial results when backend is terminated by timeout.

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.