Author: Michael Komitee <mkomitee@vonage.com>
License: BSD License
Copyright (c) 2007, Vonage Holdings
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.
* Neither the name of Vonage Holdings nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
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 OWNER OR 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.
= Asterisk Ruby Framework -- AGI for Ruby
AGI, AGIMenu, AGISelection, and AGIServer work together with their supporting libraries to complete an Asterisk AGI Framework for applications.
* AGI: handles interaction between ruby and Asterisk. Asterisk connects to the AGI via either pipes or sockets
* AGIMenu: implements more complex logic dealing with menus and prompts
* AGISelection: implements more complex logic dealing with audio playback and digit strings
* AGIServer: implements a TCPServer via a block or rails routes, which instantiates AGI objects for Asterisk interaction
== Download
The latest version of asterisk-ruby can be found at
* http://rubyforge.org/project/
== Installation
=== Normal Installation
Setup based installation is currently unsupported
=== GEM Installation
Download and install asterisk-ruby with the following.
% gem install asterisk-ruby
== Usage, ...
=== AGI
The AGI object can be used to interact with an Asterisk. It can be used within the AGIServer framework, or independantly. Simply instantiate an AGI object and pass it input and output IO objects. Asterisk extensions can exec an agi script (in asterisk parlance, agi or deadagi), in which case you'll want to use stdin and stdout, or asterisk extensions can connect to a daemonized agi server (in asterisk parlance, fagi) and you'd want to use a tcp socket.
agi = AGI.new(:input => STDIN, :output => STDOUT)
agi.init
agi.answer
agi.hangup
Note, all agi instances will be uninitialized. The initialization process of an agi channel must be performed before any other interaction with the channel can be accomplished.
=== AGIMenu
Sometimes when dealing with Asterisk AGI, a generic AGIMenu object can come in handy. Thats where the aptly named AGIMenu object comes into play. With AGIMenu, you can configure a menu of options based on a yaml configuration or a hash. For example:
AGIMenu.sounds_dir = 'agimenu-test/sounds/'
hash = {:introduction=>["welcome", "instructions"],
:conclusion=>"what-is-your-choice",
:timeout=>17,
:choices=>
[{:dtmf=>"*", :audio=>["to-go-back", "press", "digits/star"]},
{:dtmf=>1, :audio=>["press", "digits/1", "for-option-1"]},
{:dtmf=>2, :audio=>["press", "digits/2", "for-option-2"]},
{:dtmf=>"#", :audio=>["or", "press", "digits/pound", "to-repeat"]}]}
menu = AGIMenu.new(hash)
menu.play(:agi => AGI.new())
This results in Asterisk using sounds in it's agimenu-test/sounds directory to play a menu which accepts the DTMF *, 1, 2, or #. It will first play the introduction sound files 'welcome' and 'instructions', then play the menu sound files 'to-go-back' 'press' 'digits/star' 'press' 'digits/1' 'for-option-1' 'press 'digits/2' 'for-option-2' 'or' 'press' 'digits/pound' 'to-repeat', and then play the conslusion sound file 'what-is-your-choice' and then wait 17 seconds.
You could hand AGIMenu.new() a filename, a file, a yaml oject, a hash, or nothing at all. You can then modify the menu with the classes various methods.
=== AGISelection
AGISelection can be used to get a string of digits from an asterisk channel. You configure it similarly to an AGIMenu, but it takes a max_digits paramater and only accepts a single audio file. AGIMenu only accepts a single dtmf digit, whereas AGISelection can accept multiple digits. It would be used to have a user input a PIN or a telephone number or something similar.
agi = AGI.new()
yaml_hash = {:audio => 'tt-monkeys', :max_digits => 4}
foo = AGISelection.new(yaml_hash)
foo.read(:agi => AGI.new())
=== AGIServer
There are several ways to use the AGIServer module. All of them have a few things in common. In general, since we're creating a server, we need a way to cleanly kill it. So we setup sigint anf sigterm handlers to shutdown all instances of AGIServer Objects
trap('INT') { AGIServer.shutdown }
trap('TERM') { AGIServer.shutdown }
We also tend to use a logger because this should be daemonized. While developing, I reccomend you log to STDERR
logger = Logger.new(STDERR)
logger.level = Logger::DEBUG
I use YAML for configuration options. This just sets up the bind port, address, and some threading configuration options.
config = YAML.load_file('config/example-config.yaml')
config[:logger] = logger
config[:params] = {:custom1 => 'data1'}
And then we generate our server
begin
MyAgiServer = AGIServer.new(config)
rescue Errno::EADDRINUSE
error = "Cannot start MyAgiServer, Address already in use."
logger.fatal(error)
print "#{error}\n"
exit
else
print "#{$$}"
end
In this example, I'll show you the rails-routing means of working with the AGIServer. Define a Route class along with a few routes, and start the server.
class TestRoutes < AGIRoute
def sample
agi.answer
print "CUSTOM1 = [#{params[:custom1]}]\n"
print "URI = [#{request[:uri]}]\n"
print "ID = [#{request[:id]}]\n"
print "METHOD = [#{request[:method]}]\n"
print "OPTIONS = #{request[:options].pretty_inspect}"
print "FOO = [#{request[:options]['foo']}]\n"
print '-' * 10 + "\n"
helper_method
agi.hangup
end
private
def helper_method
print "I'm private which means I'm not accessible as a route!\n"
end
end
MyAgiServer.start
MyAgiServer.finish
Pointing an asterisk extension at agi://localhost:4573/TestRoutes/sample/1/?foo=bar will execute the sample method in the TestRoutes class.
In this example, I'll show you how to use a block to define the AGI logic. Simply start the server and pass it a block expecting an agi object:
MyAgiServer.start do |agi|
agi.answer
puts "I'm Alive!"
agi.hangup
end
MyAgiServer.finish
In this example, I'll show you another way to use a block to define the AGI logic. This block makes configuration parameters available during the call:
MyAgiServer.start do |agi,params|
agi.answer
print "PARAMS = #{params.pretty_inspect}"
agi.hangup
end
MyAgiServer.finish