Asterisk Gateway Interface (AGI)

The AGI interface consists of a number of action classes that are sent to Asterisk to effect actions on active channels. Two different means of getting access to a channel are defined: AGI and FastAGI, with the difference between them being that every AGI instance runs as a child process of Asterisk (full Python interpreter and everything), while FastAGI runs over a TCP/IP socket, allowing for faster startup times and lower overhead, with the cost of a little more development investment.

pystrix exposes the same feature-set and interaction model for both AGI and FastAGI, allowing any of the actions defined in the following sections to be instantiated and passed (any number of times) to agi.AGI.execute().

Members

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

Classes

class agi.AGI(debug=False)

An interface to Asterisk, exposing request-response functions for synchronous management of the call associated with this channel.

execute(action)

Sends a request to Asterisk and waits for a response before returning control to the caller.

The given _Action object, action, carries the command, arguments, and result-processing logic used to communicate with Asterisk.

The state of the channel is verified with each call to this function, to ensure that it is still connected. An instance of AGIHangup is raised if it is not.

get_environment()

Returns Asterisk’s initial environment variables as a dictionary.

Note that this function returns a copy of the values, so repeated calls are less favourable than storing the returned value locally and dissecting it there.

class agi.FastAGIServer(interface='127.0.0.1', port=4573, daemon_threads=True, debug=False)

Provides a FastAGI TCP server to handle requests from Asterisk servers.

timeout

The number of seconds to wait for a request when using handle_request(). Has no effect on serve_forever().

handle_request()

Handles at most one request in a separate thread or times out and returns control silently.

serve_forever()

Continues to serve requests as they are received, handling each in a new thread, until shutdown() is called.

shutdown()

Interrupts serve_forever() gracefully.

clear_script_handlers()

Empties the list of script handlers, allowing it to be repopulated. The default handler is not cleared by this action; to clear it, call register_script_handler(None, None).

get_script_handler(script_path)

Provides the callable specified to handle requests received by this FastAGI server and the result of matching, as a tuple.

script_path is the path received from Asterisk.

register_script_handler(regex, handler)

Registers the given handler, which is a callable that accepts an AGI object used to communicate with the Asterisk channel, a tuple containing any positional arguments, a dictionary containing any keyword arguments (values are enumerated in a list), the match object (may be None), and the original script address as a string.

Handlers are resolved by regex, which may be a regular expression object or a string, match in the order in which they were supplied, so provide more specific qualifiers first.

The special regex value None sets the default handler, invoked when every comparison fails; this is preferable to adding a catch-all handler in case the list is changed at runtime. Setting the default handler to None disables the catch-all, which will typically make Asterisk just drop the call.

unregister_script_handler(regex)

Removes a specific script-handler from the list, given the same regex object used to register it initially.

This function should only be used when a specific handler is no longer useful; if you want to re-introduce handlers, consider using clear_script_handlers() and re-adding all handlers in the desired order.

Exceptions

exception agi.AGIException(message, items=None)

Bases: exceptions.Exception

The base exception from which all exceptions native to this module inherit.

items

A dictionary containing any key-value items received from Asterisk to explain the exception.

exception agi.AGIError(message, items=None)

Bases: pystrix.agi.agi_core.AGIException

The base error from which all errors native to this module inherit.

exception agi.AGIUnknownError(message, items=None)

Bases: pystrix.agi.agi_core.AGIError

An error raised when an unknown response is received from Asterisk.

exception agi.AGIAppError(message, items=None)

Bases: pystrix.agi.agi_core.AGIError

An error raised when an attempt to make use of an Asterisk application fails.

exception agi.AGIHangup(message, items=None)

Bases: pystrix.agi.agi_core.AGIException

The base exception used to indicate that the call has been completed or abandoned.

exception agi.AGISIGPIPEHangup(message, items=None)

Bases: pystrix.agi.agi_core.AGIHangup

Indicates that the communications pipe to Asterisk has been severed.

exception agi.AGISIGHUPHangup(message, items=None)

Bases: pystrix.agi.agi_core.AGIHangup

Indicates that the script’s process received the SIGHUP signal, implying Asterisk has hung up the call. Specific to script-based instances.

exception agi.AGIResultHangup(message, items=None)

Bases: pystrix.agi.agi_core.AGIHangup

Indicates that Asterisk received a clean hangup event.

exception agi.AGIDeadChannelError(message, items=None)

Bases: pystrix.agi.agi_core.AGIError

Indicates that a command was issued on a channel that can no longer process it.

exception agi.AGIUsageError(message, items=None)

Bases: pystrix.agi.agi_core.AGIError

Indicates that a request made to Asterisk was sent with invalid syntax.

exception agi.AGIInvalidCommandError(message, items=None)

Bases: pystrix.agi.agi_core.AGIError

Indicates that a request made to Asterisk was not understood.