StarPy is a Python + Twisted protocol that provides access to the Asterisk PBX's Manager Interface (AMI) and Fast Asterisk Gateway Interface (FastAGI). Together these allow you write both command-and-control interfaces (used, for example to generate new calls) and to customise user interactions from the dial-plan.
StarPy
is still early in its life cycle and shouldn't be used in production
environments unless you feel comfortable hacking on the code
yourself. Its author
is very interested in bug reports and feedback and is available for
extending/customisation contracts.
StarPy is a pure-Python distutils extension. Simply unpack the source archive to a temporary directory and run:
python setup.py install
You will need Python 2.3+ and Twisted (Core) installed.
StarPy provides most of the hooks you want to use on the protocol instances. The AMI client is created by a client factory, as is standard for Twisted operation. You create a factory like so:
from starpy import manager
f = manager.AMIFactory(sys.argv[1], sys.argv[2])
df = f.login('server',port)
The factory takes the username and secret (password) for the Asterisk manager interface (note: do not actually pass in these values on the command-line in a real application, as this would expose the username and password to anyone on the machine). The deferred object returned from the login call will fire when the AMI connection has been established and authenticated. You register callbacks on the deferred to accomplish those tasks you'd like to accomplish.
You will need to configure
Asterisk to have the AMI enabled and choose the username, password in
/etc/asterisk/manager.conf . Please keep in mind that the AMI
interface is not encrypted, so should never be run across an insecure
network.
The return value for the callback is an AMIProtocol instance. The various methods on the AMIProtocol generally handle the creation and interpretation of "Action ID" fields. The return value for most methods is an event, message or list of events. Messages and events are modeled as dictionaries with lower-case keys.
See the examples/connecttoivr.py script for sample usage of the AMIProtocol
Again, most of the hooks you want to use are provided on the protocol instances. FastAGI is a server, and is thus created by a (non-client) factory like so:
from starpy import fastagi
f = fastagi.FastAGIFactory(testFunction)
reactor.listenTCP( 4573, f, 50, '127.0.0.1')
The testFunction there is the operation to undertake when the Asterisk Server connects to the FastAGI server. It takes a (connected) FastAGIProtocol instance as its only argument.
You use a FastAGI application from your Dial Plan with a like like this (note: arguments do not appear to be passed to FastAGI scripts, unlike regular AGI scripts):
exten => 1000,3,AGI(agi://127.0.0.1:4573)
Please keep in mind that the
FastAGI interface is neither encrypted nor authenticating! It
should never be run across an insecure network and should never be run
on a port that is accessible from a public network.
See the examples directory for examples of FastAGI scripts.
StarPy is licensed under
extremely liberal terms.
Copyright (c) 2006, Michael C. Fletcher
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
The name of Michael C. Fletcher, or the name of any Contributor,
may not be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS NOT FAULT TOLERANT AND SHOULD NOT BE USED IN ANY
SITUATION ENDANGERING HUMAN LIFE OR PROPERTY.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.