By default, Asterisk exposes a number of ways to interact with a channel, all of which are described below.
All of the following objects should be accessed as part of the agi.core namespace, regardless of the modules in which they are defined.
Channel is down and available
Channel is down and reserved
Channel is off-hook
A destination address has been specified
The channel is locally ringing
The channel is remotely ringing
The channel is connected
The channel is in a busy, non-conductive state
Selects the sln audio format
Selects the g723 audio format
Selects the g729 audio format
Selects the gsm audio format
Selects the alaw audio format
Selects the ulaw audio format
Selects the vox audio format
Selects the wav audio format
The Asterisk logging level equivalent to ‘debug’
The Asterisk logging level equivalent to ‘info’
The Asterisk logging level equivalent to ‘warn’
The Asterisk logging level equivalent to ‘error’
The Asterisk logging level equivalent to ‘critical’
Sets TDD to on
Sets TDD to off
Sets TDD to mate
Answers the call on the channel.
If the channel has already been answered, this is a no-op.
AGIAppError is raised on failure, most commonly because the connection could not be established.
Provides the current state of this channel or, if channel is set, that of the named channel.
Returns one of the channel-state constants listed below:
The value returned is an integer in the range 0-7; values outside of that range were undefined at the time of writing, but will be returned verbatim. Applications unprepared to handle unknown states should raise an exception upon their receipt or otherwise handle the code gracefully.
AGIAppError is raised on failure, most commonly because the channel is in a hung-up state.
See also GetData, GetOption, StreamFile.
Plays back the specified file, which is the filename of the file to be played, either in an Asterisk-searched directory or as an absolute path, without extension. (‘myfile.wav’ would be specified as ‘myfile’, to allow Asterisk to choose the most efficient encoding, based on extension, for the channel)
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received.
sample_offset may be used to jump an arbitrary number of milliseconds into the audio data.
If specified, forward, rewind, and pause are DTMF characters that will seek forwards and backwards in the audio stream or pause it temporarily; by default, these features are disabled.
If a DTMF key is received, it is returned as a string. If nothing is received or the file could not be played back (see Asterisk logs), None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Deletes the specified family/key entry from Asterisk’s database.
AGIAppError is raised on failure.
AGIDBError is raised if the key could not be removed, which usually indicates that it didn’t exist in the first place.
Deletes the specificed family (and optionally keytree) from Asterisk’s database.
AGIAppError is raised on failure.
AGIDBError is raised if the family (or keytree) could not be removed, which usually indicates that it didn’t exist in the first place.
Retrieves the value of the specified family/key entry from Asterisk’s database.
AGIAppError is raised on failure.
AGIDBError is raised if the key could not be found or if some other database problem occurs.
Inserts or updates value of the specified family/key entry in Asterisk’s database.
AGIAppError is raised on failure.
AGIDBError is raised if the key could not be inserted or if some other database problem occurs.
Executes an arbitrary Asterisk application with the given options, returning that application’s output.
options is an optional sequence of arguments, with any double-quote characters or commas explicitly escaped.
AGIAppError is raised if the application could not be executed.
See also ControlStreamFile, GetOption, StreamFile.
Plays back the specified file, which is the filename of the file to be played, either in an Asterisk-searched directory or as an absolute path, without extension. (‘myfile.wav’ would be specified as ‘myfile’, to allow Asterisk to choose the most efficient encoding, based on extension, for the channel)
timeout is the number of milliseconds to wait between DTMF presses or following the end of playback if no keys were pressed to interrupt playback prior to that point. It defaults to 2000.
max_digits is the number of DTMF keypresses that will be accepted. It defaults to 255.
The value returned is a tuple consisting of (dtmf_keys:str, timeout:bool). ‘#’ is always interpreted as an end-of-event character and will never be present in the output.
AGIAppError is raised on failure, most commonly because no keys, aside from ‘#’, were entered.
Returns a variable associated with this channel, with full expression-processing.
The value of the requested variable is returned as a string. If the variable is undefined, None is returned.
AGIAppError is raised on failure.
See also ControlStreamFile, GetData, StreamFile.
Plays back the specified file, which is the filename of the file to be played, either in an Asterisk-searched directory or as an absolute path, without extension. (‘myfile.wav’ would be specified as ‘myfile’, to allow Asterisk to choose the most efficient encoding, based on extension, for the channel)
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received.
timeout is the number of milliseconds to wait following the end of playback if no keys were pressed to interrupt playback prior to that point. It defaults to 2000.
The value returned is a tuple consisting of (dtmf_key:str, offset:int), where the offset is the number of milliseconds that elapsed since the start of playback, or None if playback completed successfully or the sample could not be opened.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Returns a variable associated with this channel.
The value of the requested variable is returned as a string. If the variable is undefined, None is returned.
AGIAppError is raised on failure.
Hangs up this channel or, if channel is set, the named channel.
AGIAppError is raised on failure.
Does nothing.
Good for testing the connection to the Asterisk server, like a ping, but not useful for much else. If you wish to log information through Asterisk, use the verbose method instead.
AGIAppError is raised on failure.
Receives a single character of text from a supporting channel, discarding anything else in the character buffer.
timeout is the number of milliseconds to wait for a character to be received, defaulting to infinite.
The value returned is a tuple of the form (char:str, timeout:bool), with the timeout element indicating whether the function returned because of a timeout, which may result in an empty string. None is returned if the channel does not support text.
AGIAppError is raised on failure.
Receives a block of text from a supporting channel.
timeout is the number of milliseconds to wait for text to be received, defaulting to infinite. Presumably, the first block received is immediately returned in full.
The value returned is a string.
AGIAppError is raised on failure.
Records audio to the specified file, which is the filename of the file to be written, defaulting to Asterisk’s sounds path or an absolute path, without extension. (‘myfile.wav’ would be specified as ‘myfile’) format is one of the following, which sets the extension and encoding, with WAV being the default:
The filename may also contain the special string ‘%d’, which Asterisk will replace with an auto-incrementing number, with the resulting filename appearing in the ‘RECORDED_FILE’ channel variable.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received.
timeout is the number of milliseconds to wait following the end of playback if no keys were pressed to end recording prior to that point. By default, it waits forever.
sample_offset may be used to jump an arbitrary number of milliseconds into the audio data.
beep, if True, the default, causes an audible beep to be heard when recording begins.
silence, if given, is the number of seconds of silence to allow before terminating recording early.
The value returned is a tuple consisting of (dtmf_key:str, offset:int, timeout:bool), where the offset is the number of milliseconds that elapsed since the start of playback dtmf_key may be the empty string if no key was pressed, and timeout is False if recording ended due to another condition (DTMF or silence).
The raising of AGIResultHangup is another condition that signals a successful recording, though it also means the user hung up.
AGIAppError is raised on failure, most commonly because the destination file isn’t writable.
Reads an alphabetic string of characters.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads the date associated with seconds since the UNIX Epoch. If not given, the local time is used.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads the datetime associated with seconds since the UNIX Epoch. If not given, the local time is used.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
format defaults to “ABdY ‘digits/at’ IMp”, but may be a string with any of the following meta-characters (or single-quote-escaped sound-file references):
timezone may be a string in standard UNIX form, like ‘America/Edmonton’. If format is undefined, timezone is ignored and left to default to the system’s local value.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads a numeric string of digits.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads a number naturally.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads a phonetic string of characters.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Reads the time associated with seconds since the UNIX Epoch. If not given, the local time is used.
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received and it is returned. If nothing is recieved, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Sends the specified image, which is the filename of the file to be presented, either in an Asterisk-searched directory or as an absolute path, without extension. (‘myfile.png’ would be specified as ‘myfile’, to allow Asterisk to choose the most efficient encoding, based on extension, for the channel)
AGIAppError is raised on failure.
Sends the specified text on a supporting channel.
AGIAppError is raised on failure.
Instructs Asterisk to hang up the channel after the given number of seconds have elapsed.
Calling this function with seconds set to 0, the default, will disable auto-hangup.
AGIAppError is raised on failure.
Sets the called ID (number and, optionally, name) of Asterisk on this channel.
AGIAppError is raised on failure.
Sets the context for Asterisk to use upon completion of this AGI instance.
No context-validation is performed; specifying an invalid context will cause the call to terminate unexpectedly.
AGIAppError is raised on failure.
Sets the extension for Asterisk to use upon completion of this AGI instance.
No extension-validation is performed; specifying an invalid extension will cause the call to terminate unexpectedly.
AGIAppError is raised on failure.
Enables or disables music-on-hold for this channel, per the state of the on argument.
If specified, moh_class identifies the music-on-hold class to be used.
AGIAppError is raised on failure.
Sets the priority for Asterisk to use upon completion of this AGI instance.
No priority-validation is performed; specifying an invalid priority will cause the call to terminate unexpectedly.
AGIAppError is raised on failure.
Sets the variable identified by name to value on the current channel.
AGIAppError is raised on failure.
See also ControlStreamFile, GetData, GetOption.
Plays back the specified file, which is the filename of the file to be played, either in an Asterisk-searched directory or as an absolute path, without extension. (‘myfile.wav’ would be specified as ‘myfile’, to allow Asterisk to choose the most efficient encoding, based on extension, for the channel)
escape_digits may optionally be a list of DTMF digits, specified as a string or a sequence of possibly mixed ints and strings. Playback ends immediately when one is received.
sample_offset may be used to jump an arbitrary number of milliseconds into the audio data.
The value returned is a tuple consisting of (dtmf_key:str, offset:int), where the offset is the number of milliseconds that elapsed since the start of playback, or None if playback completed successfully or the sample could not be opened.
AGIAppError is raised on failure, most commonly because the channel was hung-up.
Sets the TDD transmission mode on supporting channels, one of the following:
True is returned if the mode is set, False if the channel isn’t capable, and AGIAppError is raised if a problem occurs. According to documentation from 2006, all non-capable channels will cause an exception to occur.
Causes Asterisk to process message, logging it to console or disk, depending on whether level is greater-than-or-equal-to Asterisk’s corresponding verbosity threshold.
level is one of the following, defaulting to LOG_INFO:
AGIAppError is raised on failure.
Waits for up to timeout milliseconds for a DTMF keypress to be received, returning that value. By default, this function blocks indefinitely.
If no DTMF key is pressed, None is returned.
AGIAppError is raised on failure, most commonly because the channel was hung-up.