Core

By default, Asterisk exposes a number of ways to interact with a channel, all of which are described below.

Members

All of the following objects should be accessed as part of the agi.core namespace, regardless of the modules in which they are defined.

Constants

CHANNEL_DOWN_AVAILABLE

Channel is down and available

CHANNEL_DOWN_RESERVED

Channel is down and reserved

CHANNEL_OFFHOOK

Channel is off-hook

CHANNEL_DIALED

A destination address has been specified

CHANNEL_ALERTING

The channel is locally ringing

CHANNEL_REMOTE_ALERTING

The channel is remotely ringing

CHANNEL_UP

The channel is connected

CHANNEL_BUSY

The channel is in a busy, non-conductive state

FORMAT_SLN

Selects the sln audio format

FORMAT_G723

Selects the g723 audio format

FORMAT_G729

Selects the g729 audio format

FORMAT_GSM

Selects the gsm audio format

FORMAT_ALAW

Selects the alaw audio format

FORMAT_ULAW

Selects the ulaw audio format

FORMAT_VOX

Selects the vox audio format

FORMAT_WAV

Selects the wav audio format

LOG_DEBUG

The Asterisk logging level equivalent to ‘debug’

LOG_INFO

The Asterisk logging level equivalent to ‘info’

LOG_WARN

The Asterisk logging level equivalent to ‘warn’

LOG_ERROR

The Asterisk logging level equivalent to ‘error’

LOG_CRITICAL

The Asterisk logging level equivalent to ‘critical’

TDD_ON

Sets TDD to on

TDD_OFF

Sets TDD to off

TDD_MATE

Sets TDD to mate

Actions

class agi.core.Answer

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.

class agi.core.ChannelStatus(channel=None)

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:

  • CHANNEL_DOWN_AVAILABLE: Channel is down and available
  • CHANNEL_DOWN_RESERVED: Channel is down and reserved
  • CHANNEL_OFFHOOK: Channel is off-hook
  • CHANNEL_DIALED: A destination address has been specified
  • CHANNEL_ALERTING: The channel is locally ringing
  • CHANNEL_REMOTE_ALERTING: The channel is remotely ringing
  • CHANNEL_UP: The channel is connected
  • CHANNEL_BUSY: The channel is in a busy, non-conductive state

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.

class agi.core.ControlStreamFile(filename, escape_digits='', sample_offset=0, forward='', rewind='', pause='')

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.

class agi.core.DatabaseDel(family, key)

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.

class agi.core.DatabaseDeltree(family, keytree=None)

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.

class agi.core.DatabaseGet(family, key)

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.

class agi.core.DatabasePut(family, key, value)

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.

class agi.core.Exec(application, options=())

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.

class agi.core.GetData(filename, timeout=2000, max_digits=255)

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.

class agi.core.GetFullVariable(variable)

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.

class agi.core.GetOption(filename, escape_digits='', timeout=2000)

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.

class agi.core.GetVariable(variable)

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.

class agi.core.Hangup(channel=None)

Hangs up this channel or, if channel is set, the named channel.

AGIAppError is raised on failure.

class agi.core.Noop

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.

class agi.core.ReceiveChar(timeout=0)

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.

class agi.core.ReceiveText(timeout=0)

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.

class agi.core.RecordFile(filename, format='wav', escape_digits='', timeout=-1, sample_offset=0, beep=True, silence=None)

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:

  • FORMAT_SLN
  • FORMAT_G723
  • FORMAT_G729
  • FORMAT_GSM
  • FORMAT_ALAW
  • FORMAT_ULAW
  • FORMAT_VOX
  • FORMAT_WAV: PCM16

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.

class agi.core.SayAlpha(characters, escape_digits='')

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.

class agi.core.SayDate(seconds=None, escape_digits='')

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.

class agi.core.SayDatetime(seconds=None, escape_digits='', format=None, timezone=None)

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):

  • A: Day of the week
  • B: Month (Full Text)
  • m: Month (Numeric)
  • d: Day of the month
  • Y: Year
  • I: Hour (12-hour format)
  • H: Hour (24-hour format)
  • M: Minutes
  • p: AM/PM
  • Q: Shorthand for Today, Yesterday or ABdY
  • R: Shorthand for HM
  • S: Seconds
  • T: Timezone

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.

class agi.core.SayDigits(digits, escape_digits='')

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.

class agi.core.SayNumber(number, escape_digits='')

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.

class agi.core.SayPhonetic(characters, escape_digits='')

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 received, None is returned.

AGIAppError is raised on failure, most commonly because the channel was hung-up.

class agi.core.SayTime(seconds=None, escape_digits='')

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 received, None is returned.

AGIAppError is raised on failure, most commonly because the channel was hung-up.

class agi.core.SendImage(filename)

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.

class agi.core.SendText(text)

Sends the specified text on a supporting channel.

AGIAppError is raised on failure.

class agi.core.SetAutohangup(seconds=0)

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.

class agi.core.SetCallerid(number, name=None)

Sets the called ID (number and, optionally, name) of Asterisk on this channel.

AGIAppError is raised on failure.

class agi.core.SetContext(context)

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.

class agi.core.SetExtension(extension)

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.

class agi.core.SetMusic(on, moh_class=None)

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.

class agi.core.SetPriority(priority)

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.

class agi.core.SetVariable(name, value)

Sets the variable identified by name to value on the current channel.

AGIAppError is raised on failure.

class agi.core.StreamFile(filename, escape_digits='', sample_offset=0)

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.

class agi.core.TDDMode(mode)

Sets the TDD transmission mode on supporting channels, one of the following:

  • TDD_ON
  • TDD_OFF
  • TDD_MATE

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.

class agi.core.Verbose(message, level=1)

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:

  • LOG_DEBUG
  • LOG_INFO
  • LOG_WARN
  • LOG_ERROR
  • LOG_CRITICAL

AGIAppError is raised on failure.

class agi.core.WaitForDigit(timeout=-1)

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.

Exceptions

exception agi.core.AGIDBError(message, items=None)

Bases: pystrix.agi.agi_core.AGIAppError

Indicates that Asterisk encountered an error while interactive with its database.