Read()

Since 1.6.1.0 Applications

Read a variable.

Last reviewed 2026-04-25

Read(variable[,filenames,maxdigits,options,attempts,timeout])

Dialplan Builder -- build your Read() command

variable

The input digits will be stored in the given *variable* name.

filename

maxdigits (optional)

Maximum acceptable number of digits. Stops reading after *maxdigits* have been entered (without requiring the user to press the `#` key).

options (optional)

attempts (optional)

If greater than `1`, that many *attempts* will be made in the event no data is entered.

timeout (optional)

The number of seconds to wait for a digit response. If greater than `0`, that value will override the default timeout. Can be floating point.

Full arguments reference

variable required - The input digits will be stored in the given variable name.
filenames - Ampersand separated list of filenames to play before reading digits or tone with option i. 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.
- filename required
- filename2 (multiple)
maxdigits - Maximum acceptable number of digits. Stops reading after maxdigits have been entered (without requiring the user to press the # key).
options
- s - to return immediately if the line is not up.
- i - to play filename as an indication tone from your indications.conf.
- n - to read digits even if the line is not up.
- t - Terminator digit(s) to use for ending input. Default is #. If you need to read the digit # literally, you should remove or change the terminator character. Multiple terminator characters may be specified. If no terminator digit is present, input cannot be ended using digits and you will need to rely on duration and max digits for ending input.
- e - to read the terminator as the digit string if the only digit read is the terminator. This is for cases where the terminator is a valid digit, but only by itself. ie; 1234 and # are valid, but 1234# is not.
attempts - If greater than 1, that many attempts will be made in the event no data is entered.
timeout - The number of seconds to wait for a digit response. If greater than 0, that value will override the default timeout. Can be floating point.

Description

Reads a #-terminated string of digits a certain number of times from the user in to the given variable.

This application sets the following channel variable upon completion:

READSTATUS - This is the status of the read operation.
- OK
- ERROR
- HANGUP
- INTERRUPTED
- SKIPPED
- TIMEOUT

Arguments

variable required - The input digits will be stored in the given variable name.
filenames - Ampersand separated list of filenames to play before reading digits or tone with option i. 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.
- filename required
- filename2 (multiple)
maxdigits - Maximum acceptable number of digits. Stops reading after maxdigits have been entered (without requiring the user to press the # key).
options
- s - to return immediately if the line is not up.
- i - to play filename as an indication tone from your indications.conf.
- n - to read digits even if the line is not up.
- t - Terminator digit(s) to use for ending input. Default is #. If you need to read the digit # literally, you should remove or change the terminator character. Multiple terminator characters may be specified. If no terminator digit is present, input cannot be ended using digits and you will need to rely on duration and max digits for ending input.
- e - to read the terminator as the digit string if the only digit read is the terminator. This is for cases where the terminator is a valid digit, but only by itself. ie; 1234 and # are valid, but 1234# is not.
attempts - If greater than 1, that many attempts will be made in the event no data is entered.
timeout - The number of seconds to wait for a digit response. If greater than 0, that value will override the default timeout. Can be floating point.

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.