Play a sound file

When using Adhearsion with Asterisk, you have [hundreds](http://www.voip-info.org/wiki/view/Asterisk+sound+files) of sound files to use right out of the box. These range from the useful everyday sound files to pure novelties such as monkeys screaming and practical jokes. To play a sound file, use the [``play``](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#play-instance_method) method like below. # Ruby play "hello-world" You can play multiple files in sequence too. # Ruby play "please-enter-your", "extension" If this is your first time seeing Ruby, ``play`` is actually a method. Ruby does not require you wrap a method's arguments with parenthesis.

When using Adhearsion with Asterisk, you have <a href="http://www.voip-info.org/wiki/view/Asterisk+sound+files">hundreds</a> of sound files to use right out of the box. These range from the useful everyday sound files to pure novelties such as monkeys screaming and practical jokes. To play a sound file, use the <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#play-instance_method"><code>play</code></a> method like below. <pre class="syntax-ruby">play "hello-world" </pre> You can play multiple files in sequence too. <pre class="syntax-ruby">play "please-enter-your", "extension" </pre> If this is your first time seeing Ruby, <code>play</code> is actually a method. Ruby does not require you wrap a method's arguments with parenthesis.

2009-02-16T03:50:14Z

1 1 Play a sound file

2009-02-19T02:30:39Z

Adhearsion creates a number of variables for you when it runs your dialplan which are available in any context you may jump around to. For example, the following dialplan will speak back whatever extension the user dials. # Ruby adhearsion { play extension } The ``extension`` variable in this case is actually not an variable. It's a method that, because of Ruby's cleanliness, simply look like local variable. This may be a little confusing to you at first. Consider the following example: # Ruby adhearsion { extension = extension + 1 play extension +player } player { play extension } When the ``adhearsion`` context jumps to the ``player`` context, you may think both contexts will speak the same number. It actually won't for a slightly technical reason: When ``extension`` is defined with the ``=`` sign, Ruby will make that into a local variable and "shadow" anything else in a higher scope that may have that same name. Because the method ``extension`` is in a higher scope, the local variable will take precedence, but _only in the local scope_. The ``player`` context has its own, separate scope and, therefore, the ``extension`` instance method is used. To share information between contexts, simply use Ruby instance variables. We can rewrite the previous example properly as follows: # Ruby adhearsion { @extension = extension + 1 play @extension +player } player { play @extension } All contexts will run within the same Execution Environment object and therefore all instance variables will remain in scope no matter how many times you jump around.

Adhearsion creates a number of variables for you when it runs your dialplan which are available in any context you may jump around to. For example, the following dialplan will speak back whatever extension the user dials. <pre class="syntax-ruby">adhearsion { play extension } </pre> The <code>extension</code> variable in this case is actually not an variable. It's a method that, because of Ruby's cleanliness, simply look like local variable. This may be a little confusing to you at first. Consider the following example: <pre class="syntax-ruby">adhearsion { extension = extension + 1 play extension +player } player { play extension } </pre> When the <code>adhearsion</code> context jumps to the <code>player</code> context, you may think both contexts will speak the same number. It actually won't for a slightly technical reason: When <code>extension</code> is defined with the <code>=</code> sign, Ruby will make that into a local variable and "shadow" anything else in a higher scope that may have that same name. Because the method <code>extension</code> is in a higher scope, the local variable will take precedence, but only in the local scope. The <code>player</code> context has its own, separate scope and, therefore, the <code>extension</code> instance method is used. To share information between contexts, simply use Ruby instance variables. We can rewrite the previous example properly as follows: <pre class="syntax-ruby">adhearsion { @extension = extension + 1 play @extension +player } player { play @extension } </pre> All contexts will run within the same Execution Environment object and therefore all instance variables will remain in scope no matter how many times you jump around.

2009-02-16T04:27:58Z

2 1 Sharing variables between contexts

2009-02-20T15:42:24Z

Taking input via phone keypad input is extremely simple. # Ruby desired_extension = input The example above shows a Ruby principle at work: *convention over configuration*. All of [``input``](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#input-instance_method)'s parameters are optional. The code above simply receives any number of digits with no timeout until the user presses the "#" key. The result is then bound to the ``desired_extension`` variable with the delimiting "#" removed. Or you can explicitly receive a number of digits with a timeout. # Ruby desired_extension = input 3, :timeout => 1.minute This takes in three digits, waiting up to one minute for each successive key entry. Though a one minute timeout is a bit contrived, this example shows an interesting feature of Ruby: everything, even numbers, is an object. Objects have methods, therefore a ``minute`` method makes perfect sense.

Taking input via phone keypad input is extremely simple. <pre class="syntax-ruby">desired_extension = input </pre> The example above shows a Ruby principle at work: convention over configuration. All of <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#input-instance_method"><code>input</code></a>'s parameters are optional. The code above simply receives any number of digits with no timeout until the user presses the "#" key. The result is then bound to the <code>desired_extension</code> variable with the delimiting "#" removed. Or you can explicitly receive a number of digits with a timeout. <pre class="syntax-ruby">desired_extension = input 3, :timeout => 1.minute </pre> This takes in three digits, waiting up to one minute for each successive key entry. Though a one minute timeout is a bit contrived, this example shows an interesting feature of Ruby: everything, even numbers, is an object. Objects have methods, therefore a <code>minute</code> method makes perfect sense.

2009-02-16T06:01:04Z

3 2 Receiving keypad input

2009-02-19T02:30:39Z

Want the user to join a conference bridge? Just tell them to [join](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#join-instance_method) something. # Ruby join "sales" You can make the conference name virtually anything. For example, if you create a web-based tool to manage your company's conferences, you can make the conference name the unique ID of that conference's database record. The join method uses the Asterisk [MeetMe](http://www.voip-info.org/wiki-Asterisk+cmd+MeetMe) application. Alternatively, you may use the add-on application [Conference](http://www.voip-info.org/wiki/view/Asterisk+cmd+Conference) using the [execute](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#execute-instance_method) method as follows: # Ruby execute("Conference", "room/S")

Want the user to join a conference bridge? Just tell them to <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#join-instance_method">join</a> something. <pre class="syntax-ruby">join "sales" </pre> You can make the conference name virtually anything. For example, if you create a web-based tool to manage your company's conferences, you can make the conference name the unique ID of that conference's database record. The join method uses the Asterisk <a href="http://www.voip-info.org/wiki-Asterisk+cmd+MeetMe">MeetMe</a> application. Alternatively, you may use the add-on application <a href="http://www.voip-info.org/wiki/view/Asterisk+cmd+Conference">Conference</a> using the <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#execute-instance_method">execute</a> method as follows: <pre class="syntax-ruby">execute("Conference", "room/S") </pre>

2009-02-16T06:03:17Z

4 3 Joining a conference bridge

2009-02-19T04:32:33Z

The Adhearsion dialplan.rb mirrors the Asterisk concept of a context. Within the [extensions.conf](http://www.voip-info.org/tiki-index.php?page=Asterisk%20config%20extensions.conf) file of Asterisk you may have these [contexts](http://www.voip-info.org/wiki-Asterisk+Dialplan+Introduction): [from_dallas] exten => _X.,1,AGI(agi://localhost) exten => _X.,n,Hangup [from_chicago] exten => _X.,1,AGI(agi://localhost) exten => _X.,n,Hangup You would then have these corresponding contexts in the Adhearsion dialplan.rb: # Ruby from_texas { play 'hello', 'texas' # do more here } from_illinois { play 'hello', 'illinois' # do more here } Further, you may have additional contexts in the Adhearsion dialplan.rb that may be mixed in as follows: # Ruby from_omaha { play 'hello', 'omaha', 'and' +from_nebraska } from_nebraska { play 'hello', 'nebraska' # do more here } With this feature you may have reusable code in contexts within dialplan.rb.

The Adhearsion dialplan.rb mirrors the Asterisk concept of a context. Within the <a href="http://www.voip-info.org/tiki-index.php?page=Asterisk%20config%20extensions.conf">extensions.conf</a> file of Asterisk you may have these <a href="http://www.voip-info.org/wiki-Asterisk+Dialplan+Introduction">contexts</a>: <pre><code>[from_dallas] exten => _X.,1,AGI(agi://localhost) exten => _X.,n,Hangup [from_chicago] exten => _X.,1,AGI(agi://localhost) exten => _X.,n,Hangup </code> </pre> You would then have these corresponding contexts in the Adhearsion dialplan.rb: <pre class="syntax-ruby">from_texas { play 'hello', 'texas' # do more here } from_illinois { play 'hello', 'illinois' # do more here } </pre> Further, you may have additional contexts in the Adhearsion dialplan.rb that may be mixed in as follows: <pre class="syntax-ruby">from_omaha { play 'hello', 'omaha', 'and' +from_nebraska } from_nebraska { play 'hello', 'nebraska' # do more here } </pre> With this feature you may have reusable code in contexts within dialplan.rb.

2009-02-16T06:03:45Z

5 4 Using dialplan contexts

2009-02-19T04:52:06Z

The [menu](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#menu-instance_method) command solves the problem of building enormous input-fetching state machines in Ruby without first-class message passing facilities or an external DSL. In otherwords, build complex menus to collect actionable user input via [DTMF](http://en.wikipedia.org/wiki/Dtmf). Here is an example dialplan which uses the menu command effectively: # Ruby from_pstn { menu 'welcome', 'for-spanish-press-8', 'main-ivr', :timeout => 8.seconds, :tries => 3 do |link| link.shipment_status 1 link.ordering 2 link.representative 4 link.spanish 8 link.employee 900..999 link.on_invalid { play 'invalid' } link.on_premature_timeout do |str| play 'sorry' end link.on_failure do play 'goodbye' hangup end end } shipment_status { # Fetch a tracking number and pass it to a web service. } ordering { # Enter another menu that lets them enter credit card # information and place their order over the phone. } representative { # Place the caller into a queue } spanish { # Special options for the spanish menu. } employee { dial "SIP/#{extension}" # Overly simplistic }

The <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#menu-instance_method">menu</a> command solves the problem of building enormous input-fetching state machines in Ruby without first-class message passing facilities or an external DSL. In otherwords, build complex menus to collect actionable user input via <a href="http://en.wikipedia.org/wiki/Dtmf">DTMF</a>. Here is an example dialplan which uses the menu command effectively: <pre class="syntax-ruby">from_pstn { menu 'welcome', 'for-spanish-press-8', 'main-ivr', :timeout => 8.seconds, :tries => 3 do |link| link.shipment_status 1 link.ordering 2 link.representative 4 link.spanish 8 link.employee 900..999 link.on_invalid { play 'invalid' } link.on_premature_timeout do |str| play 'sorry' end link.on_failure do play 'goodbye' hangup end end } shipment_status { # Fetch a tracking number and pass it to a web service. } ordering { # Enter another menu that lets them enter credit card # information and place their order over the phone. } representative { # Place the caller into a queue } spanish { # Special options for the spanish menu. } employee { dial "SIP/#{extension}" # Overly simplistic } </pre>

2009-02-16T06:04:21Z

6 5 Simple menu example

2009-02-19T04:33:24Z

With Adhearsion it is easy to access an [RDBMS](http://en.wikipedia.org/wiki/RDBMS) either through Rails or directly with [ActiveRecord](http://api.rubyonrails.org/classes/ActiveRecord/Base.html). Once you have your models setup, you may fetch information in a database and then iterate over it in your dialplan.rb. In this example we will show pulling information from a database to build a [text to speech (TTS)](http://en.wikipedia.org/wiki/Text_to_speech) audio file to playback to the caller. # Ruby # my_model.rb class ParkingLot < ActiveRecord::Base end # dialplan.rb parking_spaces_available { message = "Welcome to the parking info service." # Fetch the parking lot details from the database parking_lots = ParkingLot.find(:all) # Then iterate over the results to build a menu parking_lots.each do |parking_lot| message = message + " " + parking_lot.name + " has " + parking_lot.spaces.to_s + "spaces available." end # Then if you have Festival TTS installed you may # build your TTS file and play it back to the caller filename = "parking_spaces_available.ulaw" system("echo #{message} | text2wave -o #{filename} -otype ulaw") play filename }

With Adhearsion it is easy to access an <a href="http://en.wikipedia.org/wiki/RDBMS">RDBMS</a> either through Rails or directly with <a href="http://api.rubyonrails.org/classes/ActiveRecord/Base.html">ActiveRecord</a>. Once you have your models setup, you may fetch information in a database and then iterate over it in your dialplan.rb. In this example we will show pulling information from a database to build a <a href="http://en.wikipedia.org/wiki/Text_to_speech">text to speech (TTS)</a> audio file to playback to the caller. <pre class="syntax-ruby"># my_model.rb class ParkingLot < ActiveRecord::Base end # dialplan.rb parking_spaces_available { message = "Welcome to the parking info service." # Fetch the parking lot details from the database parking_lots = ParkingLot.find(:all) # Then iterate over the results to build a menu parking_lots.each do |parking_lot| message = message + " " + parking_lot.name + " has " + parking_lot.spaces.to_s + "spaces available." end # Then if you have Festival TTS installed you may # build your TTS file and play it back to the caller filename = "parking_spaces_available.ulaw" system("echo #{message} | text2wave -o #{filename} -otype ulaw") play filename } </pre>

2009-02-16T06:06:33Z

9 1 Iterating over all records in a table

2009-02-19T17:21:20Z

In this example we will show finding one record from the database and using information from that row. # Ruby # my_model.rb class ParkingLot < ActiveRecord::Base end # dialplan.rb parking_lot_menu { menu 'welcome', 'for-bush-st-press1', 'for-hyde-press2', :timeout => 8.seconds, :tries => 3 do |link| link.bush_st 1 link.hyde_st 2 } bush_st { # Here you may see we find the parking lot name # based on the column 'name' parking_lot = ParkingLot.find(:first, :conditions => { :name => "Bush St" }) play "bush-st-has", parking_lot.spaces, "spaces-available" } hyde_st { # Do the same thing here }

In this example we will show finding one record from the database and using information from that row. <pre class="syntax-ruby"># my_model.rb class ParkingLot < ActiveRecord::Base end # dialplan.rb parking_lot_menu { menu 'welcome', 'for-bush-st-press1', 'for-hyde-press2', :timeout => 8.seconds, :tries => 3 do |link| link.bush_st 1 link.hyde_st 2 } bush_st { # Here you may see we find the parking lot name # based on the column 'name' parking_lot = ParkingLot.find(:first, :conditions => { :name => "Bush St" }) play "bush-st-has", parking_lot.spaces, "spaces-available" } hyde_st { # Do the same thing here } </pre>

2009-02-16T06:07:00Z

10 1 Finding the first record by a column value

2009-02-19T17:21:33Z

Creating a new [component](http://docs.adhearsion.com/display/adhearsion/Components) is easy with the built-in Adhearsion generators. From within your ~/ahn_project/ directory type: ahn create component my_shiny_new_component With this you get a directory and files as follows: # Directory ~/ahn_project/components/my_shiny_new_component # The files created are ~/ahn_project/components/my_shiny_new_component.rb ~/ahn_project/components/my_shiny_new_component.yml You may then disable the component as follows: ahn disable component my_shiny_new_component And enable as follows: ahn enable component my_shiny_new_component

Creating a new <a href="http://docs.adhearsion.com/display/adhearsion/Components">component</a> is easy with the built-in Adhearsion generators. From within your ~/ahn_project/ directory type: <pre><code>ahn create component my_shiny_new_component </code></pre> With this you get a directory and files as follows: <pre><code># Directory ~/ahn_project/components/my_shiny_new_component # The files created are ~/ahn_project/components/my_shiny_new_component.rb ~/ahn_project/components/my_shiny_new_component.yml </code></pre> You may then disable the component as follows: <pre><code>ahn disable component my_shiny_new_component </code></pre> And enable as follows: <pre><code>ahn enable component my_shiny_new_component </code></pre>

2009-02-16T06:07:13Z

11 8 Creating a new component

2009-02-19T17:40:09Z

Now that you have created your component, you may begin to create methods accessible to the different subsystems of Adhearsion. To add a method in your component that becomes available to your dialplan.rb, simply do the following: # Ruby # In your my_shiny_new_component.rb file methods_for :dialplan do def count_to_ten cnt = 0 while cnt < 11 cnt += 1 end return cnt end end # Then in your dialplan.rb the method is available inbound { ten = count_to_ten }

Now that you have created your component, you may begin to create methods accessible to the different subsystems of Adhearsion. To add a method in your component that becomes available to your dialplan.rb, simply do the following: <pre class="syntax-ruby"># In your my_shiny_new_component.rb file methods_for :dialplan do def count_to_ten cnt = 0 while cnt < 11 cnt += 1 end return cnt end end # Then in your dialplan.rb the method is available inbound { ten = count_to_ten } </pre>

2009-02-16T06:07:29Z

12 9 Adding a new dialplan method

2009-02-19T17:58:17Z

Any component methods defined within the :global scope will be available anywhere in the Ruby process. # Ruby methods_for :global do def open_door RestClient.get("http://front-door/control/open") end end When methods are defined in the global scope, you should make the assumption that you will only have access to other globally-available methods. Don't use dialplan methods such a ``play`` in your global methods; this would work when your dialplan calls the global method but blow up when another part of the framework calls it.

Any component methods defined within the :global scope will be available anywhere in the Ruby process. <pre class="syntax-ruby">methods_for :global do def open_door RestClient.get("http://front-door/control/open") end end </pre> When methods are defined in the global scope, you should make the assumption that you will only have access to other globally-available methods. Don't use dialplan methods such a <code>play</code> in your global methods; this would work when your dialplan calls the global method but blow up when another part of the framework calls it.

2009-02-16T06:07:47Z

13 10 Defining a globally-recognized method

2009-02-19T02:30:40Z

The events.rb subsystem provides all events that the Asterisk [manager.conf](http://www.voip-info.org/tiki-index.php?page=Asterisk%20config%20manager.conf) specifies for that user. Therefore you may want to deal with only certain events to trigger various actions. In the events.rb you may do something like this: # Ruby events.asterisk.manager_interface.each do |event| # I always downcase so I do not have to remember too much case event.name.downcase when "newstate" # If the call was answered if event.headers["State"] == "Up" # do something end when "hangup" # do something end end

The events.rb subsystem provides all events that the Asterisk <a href="http://www.voip-info.org/tiki-index.php?page=Asterisk%20config%20manager.conf">manager.conf</a> specifies for that user. Therefore you may want to deal with only certain events to trigger various actions. In the events.rb you may do something like this: <pre class="syntax-ruby">events.asterisk.manager_interface.each do |event| # I always downcase so I do not have to remember too much case event.name.downcase when "newstate" # If the call was answered if event.headers["State"] == "Up" # do something end when "hangup" # do something end end </pre>

2009-02-16T06:09:55Z

18 11 Handling a telephony platform event with a particular name

2009-02-19T17:33:54Z

In your component, just register a callback for the ``:after_initialized`` namespace. # Ruby initialization do Events.register_callback :after_initialized do ahn_log "Do stuff here!" end end

In your component, just register a callback for the <code>:after_initialized</code> namespace. <pre class="syntax-ruby"> initialization do Events.register_callback :after_initialized do ahn_log "Do stuff here!" end end </pre>

2009-02-16T06:10:15Z

19 12 Run code after Adhearsion fully initializes

2009-02-19T05:00:50Z

Example component for Adhearsion showing a browser-based click to call application. Also shows how to use the RESTful API of Adhearsion. You may access the component [here](http://github.com/jsgoecke/restful_clicktocall).

Example component for Adhearsion showing a browser-based click to call application. Also shows how to use the RESTful API of Adhearsion. You may access the component <a href="http://github.com/jsgoecke/restful_clicktocall">here</a>.

2009-02-16T06:11:58Z

23 0 Click to call

2009-02-20T02:53:26Z

Below is a sample PHP class you can use to talk with the Adhearsion ``restful_rpc`` component. The ``restful_rpc`` component comes disabled by default in all newly-generated applications. <?php // Define an Adhearsion PHP class for a REST HTTP connection class Adhearsion { public $url; public $username; public $password; function __construct($url, $username, $password) { $this->url = $url; $this->username = $username; $this->password = $password; } function invoke($method_name) { $json = json_encode(array_slice(func_get_args(), 1)); $url = "$this->url/$method_name"; return json_decode(http_post_data($url, $json, array("httpauth" => "$this->username:$this->password"))); } } // Connect to the REST API of Adhearsion $ahn = new Adhearsion("localhost:5000", "jicksta", "roflcopterz"); //Build an array of the options for calling $call_options = array(array ('channel' => 'SIP/303', 'context' => 'inbound', 'exten' => '1000', 'priority' => '1', 'async' => 'true', 'variable' => 'destination=304'); // Invoke the Adhearsion originate method via an HTTP POST of a JSON object $ahn->invoke("call_into_context", $call_options); ?> In this example, it does an "origination" to asynchronously call out to a SIP extension (103 in this case). When the callee answers, it will start executing the ``inbound`` Adhearsion context. In dialplan example below, we're extracting a variable set in the origination and using it to dial out again. # Ruby inbound { dial "SIP/#{get_variable('destination')}" }

Below is a sample PHP class you can use to talk with the Adhearsion <code>restful_rpc</code> component. The <code>restful_rpc</code> component comes disabled by default in all newly-generated applications. <pre><code><?php // Define an Adhearsion PHP class for a REST HTTP connection class Adhearsion { public $url; public $username; public $password; function __construct($url, $username, $password) { $this->url = $url; $this->username = $username; $this->password = $password; } function invoke($method_name) { $json = json_encode(array_slice(func_get_args(), 1)); $url = "$this->url/$method_name"; return json_decode(http_post_data($url, $json, array("httpauth" => "$this->username:$this->password"))); } } // Connect to the REST API of Adhearsion $ahn = new Adhearsion("localhost:5000", "jicksta", "roflcopterz"); //Build an array of the options for calling $call_options = array(array ('channel' => 'SIP/303', 'context' => 'inbound', 'exten' => '1000', 'priority' => '1', 'async' => 'true', 'variable' => 'destination=304'); // Invoke the Adhearsion originate method via an HTTP POST of a JSON object $ahn->invoke("call_into_context", $call_options); ?> </code> </pre> In this example, it does an "origination" to asynchronously call out to a SIP extension (103 in this case). When the callee answers, it will start executing the <code>inbound</code> Adhearsion context. In dialplan example below, we're extracting a variable set in the origination and using it to dial out again. <pre class="syntax-ruby">inbound { dial "SIP/#{get_variable('destination')}" } </pre>

2009-02-16T06:12:46Z

24 14 Talking to your Adhearsion app from PHP

2009-02-22T01:58:41Z

Adhearsion has a great RPC interface out of the box that may be accessed via [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). You may then access Adhearsion objects and methods from virtually any modern lanugage. In this case we will show Ruby consuming the web services (keep in mind Adhearsion uses [JSON](http://en.wikipedia.org/wiki/Json)): # Ruby require 'json' require 'rest_client' # First we create the class that handles the connection class RESTfulAdhearsion DEFAULT_OPTIONS = { # Note: :user and :password are non-existent by default :host => "localhost", :port => "5000", :path_nesting => "/" } def initialize(options={}) @options = DEFAULT_OPTIONS.merge options @path_nesting = @options.delete :path_nesting @host = @options.delete :host @port = @options.delete :port @url_beginning = "http://#{@host}:#{@port}#{@path_nesting}" end def method_missing(method_name, *args) JSON.parse RestClient::Resource.new(@url_beginning + method_name.to_s, @options).post(args.to_json) end end #Create our Adhearsion object connected to the RESTful API of Adhearsion Adhearsion = RESTfulAdhearsion.new(:host => "localhost", :port => 5000, :user => "jicksta", :password => "roflcopterz") # Then make a call to it to place a phone call Adhearsion.originate { :channel => "SIP/3000, :context => "outbound", :priority => "1", :exten => "1000", :async => "true" }

Adhearsion has a great RPC interface out of the box that may be accessed via <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a>. You may then access Adhearsion objects and methods from virtually any modern lanugage. In this case we will show Ruby consuming the web services (keep in mind Adhearsion uses <a href="http://en.wikipedia.org/wiki/Json">JSON</a>): <pre class="syntax-ruby">require 'json' require 'rest_client' # First we create the class that handles the connection class RESTfulAdhearsion DEFAULT_OPTIONS = { # Note: :user and :password are non-existent by default :host => "localhost", :port => "5000", :path_nesting => "/" } def initialize(options={}) @options = DEFAULT_OPTIONS.merge options @path_nesting = @options.delete :path_nesting @host = @options.delete :host @port = @options.delete :port @url_beginning = "http://#{@host}:#{@port}#{@path_nesting}" end def method_missing(method_name, *args) JSON.parse RestClient::Resource.new(@url_beginning + method_name.to_s, @options).post(args.to_json) end end #Create our Adhearsion object connected to the RESTful API of Adhearsion Adhearsion = RESTfulAdhearsion.new(:host => "localhost", :port => 5000, :user => "jicksta", :password => "roflcopterz") # Then make a call to it to place a phone call Adhearsion.originate { :channel => "SIP/3000, :context => "outbound", :priority => "1", :exten => "1000", :async => "true" } </pre>

2009-02-16T06:16:45Z

26 15 Consuming RESTful resources

2009-02-19T18:47:36Z

While Adhearsion provides an extensive set of methods to ``dialplan.rb`` files, there may be times you want to execute an Asterisk command (known as an "application" in Asterisk parlance) that has not been exposed by Adhearsion. The [``execute``](http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#execute-instance_method) method accepts as its first argument the name of the Asterisk command followed by an arbitrarily long sequence of arguments. # Ruby execute "DISA", 1234, "disa_context" Voip-Info.org has an extensive list of the available Asterisk commands [here](http://www.voip-info.org/wiki-Asterisk+-+documentation+of+application+commands). **Note:** Asterisk itself has no dialplan-level concept of arguments. The example above is equivalent to ``DISA(1234|disa_context)`` in ``extensions.conf``. When Asterisk runs the DISA command, it passes the arguments between the parenthesis as a **raw string** and it's up to the application to parse it. For this reason, you may need to pass a String as the second argument to ``execute`` to manually format a finicky command's arguments.

While Adhearsion provides an extensive set of methods to <code>dialplan.rb</code> files, there may be times you want to execute an Asterisk command (known as an "application" in Asterisk parlance) that has not been exposed by Adhearsion. The <a href="http://api.adhearsion.com/Adhearsion/VoIP/Asterisk/Commands.html#execute-instance_method"><code>execute</code></a> method accepts as its first argument the name of the Asterisk command followed by an arbitrarily long sequence of arguments. <pre class="syntax-ruby">execute "DISA", 1234, "disa_context" </pre> Voip-Info.org has an extensive list of the available Asterisk commands <a href="http://www.voip-info.org/wiki-Asterisk+-+documentation+of+application+commands">here</a>. Note: Asterisk itself has no dialplan-level concept of arguments. The example above is equivalent to <code>DISA(1234|disa_context)</code> in <code>extensions.conf</code>. When Asterisk runs the DISA command, it passes the arguments between the parenthesis as a raw string and it's up to the application to parse it. For this reason, you may need to pass a String as the second argument to <code>execute</code> to manually format a finicky command's arguments.

2009-02-19T02:59:06Z

27 16 Executing arbitrary Asterisk commands

2009-02-28T18:20:51Z

ActiveRecord is an [object-relational mapper (ORM)](http://en.wikipedia.org/wiki/Object-relational_mapping) for Ruby which makes persistent database data look exactly like Ruby objects. Because ActiveRecord handles all of the SQL for you, it will work on virtually *any* SQL server for which it has adapters. If you are not using Rails, then you may still want to access a database with your own models, which is possible with Adhearsion. When building a model, you are simply creating a class that represents the table definition as the class (ie - the columns) while each row becomes an instantiated object of that class. One thing to keep in mind is that ActiveRecord works with [conventions](http://mandhro.com/2006/06/16/designing-databases-with-activerecord-conventions/) so you will want to do some research on the best way to design your database (don't worry, AR may do legacy stuff too). With this in mind, if you have two tables named 'customers' and 'orders' you may create their models as follows: # Ruby class Customer < ActiveRecord::Base end class Order < ActiveRecord::Base end As long as you have followed conventions, that is it really. Then you may reference the table rows as follows: # Ruby customers = Customer.find(:all) customers.each do |customer| puts customer.first_name + " " + customer.last_name end

ActiveRecord is an <a href="http://en.wikipedia.org/wiki/Object-relational_mapping">object-relational mapper (ORM)</a> for Ruby which makes persistent database data look exactly like Ruby objects. Because ActiveRecord handles all of the SQL for you, it will work on virtually any SQL server for which it has adapters. If you are not using Rails, then you may still want to access a database with your own models, which is possible with Adhearsion. When building a model, you are simply creating a class that represents the table definition as the class (ie - the columns) while each row becomes an instantiated object of that class. One thing to keep in mind is that ActiveRecord works with <a href="http://mandhro.com/2006/06/16/designing-databases-with-activerecord-conventions/">conventions</a> so you will want to do some research on the best way to design your database (don't worry, AR may do legacy stuff too). With this in mind, if you have two tables named 'customers' and 'orders' you may create their models as follows: <pre class="syntax-ruby">class Customer < ActiveRecord::Base end class Order < ActiveRecord::Base end </pre> As long as you have followed conventions, that is it really. Then you may reference the table rows as follows: <pre class="syntax-ruby">customers = Customer.find(:all) customers.each do |customer| puts customer.first_name + " " + customer.last_name end </pre>

2009-02-19T03:57:30Z

28 0 Writing an ActiveRecord "model"

2009-02-19T17:21:05Z

JRuby has its own, separate gem repository and requires gems be installed using its own gem executable. If you have the normal Ruby interpreter installed on your system you would be accustomed to using the 'gem' command to install new gems. For JRuby you may simply use 'jgem'. Adhearsion has a separate jahn executable with a shebang line of #!/usr/bin/env jruby. If your jruby is available in your path, you can simply execute jahn directly as you would the ahn command. jahn start /path/to/my/app

JRuby has its own, separate gem repository and requires gems be installed using its own gem executable. If you have the normal Ruby interpreter installed on your system you would be accustomed to using the 'gem' command to install new gems. For JRuby you may simply use 'jgem'. Adhearsion has a separate jahn executable with a shebang line of #!/usr/bin/env jruby. If your jruby is available in your path, you can simply execute jahn directly as you would the ahn command. <pre><code>jahn start /path/to/my/app </code></pre>

2009-02-19T04:07:13Z

29 18 Starting Adhearsion with JRuby

2009-02-19T04:36:40Z

Provides an example Adhearsion component that exposes the Ann Arbor, MI parking lot space availability via an IVR. This example was inspired by the folks @ VoIP Tech Chat and their Perl example. You may download the component [here](http://jsgoecke.github.com/annarbor_parking/).

Provides an example Adhearsion component that exposes the Ann Arbor, MI parking lot space availability via an IVR. This example was inspired by the folks @ VoIP Tech Chat and their Perl example. You may download the component <a href="http://jsgoecke.github.com/annarbor_parking/">here</a>.

2009-02-19T18:24:02Z

31 2 Web scraping - Ann Arbor Parking

2009-02-20T02:53:26Z

The Hammer is used to generate live inbound call load on an Asterisk or any other telephony system. The Hammer also provides a facility to play DTMF tones at the beginning of a call in order to traverse an IVR menu and reach various inbound call routes. The intent is use this facility in both engineering QA as well as a tool for operations in the field to load test each and every Asterisk or voice platform implementation. You may download the component [here](http://github.com/jsgoecke/hammer).

The Hammer is used to generate live inbound call load on an Asterisk or any other telephony system. The Hammer also provides a facility to play DTMF tones at the beginning of a call in order to traverse an IVR menu and reach various inbound call routes. The intent is use this facility in both engineering QA as well as a tool for operations in the field to load test each and every Asterisk or voice platform implementation. You may download the component <a href="http://github.com/jsgoecke/hammer">here</a>.

2009-02-19T18:26:50Z

33 1 An Adhearsion Stress Tester

2009-02-20T02:53:26Z

Provides an example Adhearsion component that conducts call surveys. The component also provides a Rails GUI. You may download the component [here](http://jsgoecke.github.com/surveys/).

Provides an example Adhearsion component that conducts call surveys. The component also provides a Rails GUI. You may download the component <a href="http://jsgoecke.github.com/surveys/">here</a>.

2009-02-19T18:27:30Z

34 3 Phone Surveys

2009-02-20T02:53:23Z

Example consuming the [Yahoo Query Language](http://developer.yahoo.com/yql/). The dialplan below will ask the user for their zipcode, fetch the weather based on zipcode and then play the temperature back to the user. # Ruby sandbox { play 'welcome' response = input 5, :play => ['please-enter-your', 'zip-code'], :timeout => 10, :retries => 3 yahoo_url = 'http://query.yahooapis.com/v1/public/yql?format=json&q=' query = "SELECT * FROM weather.forecast WHERE location = " + response url = URI.encode(yahoo_url + query) json_data = open(url).read weather_data = JSON.parse json_data play 'temperature', weather_data["query"]["results"]["channel"]["item"]["condition"]["temp"] }

Example consuming the <a href="http://developer.yahoo.com/yql/">Yahoo Query Language</a>. The dialplan below will ask the user for their zipcode, fetch the weather based on zipcode and then play the temperature back to the user. <pre class="syntax-ruby">sandbox { play 'welcome' response = input 5, :play => ['please-enter-your', 'zip-code'], :timeout => 10, :retries => 3 yahoo_url = 'http://query.yahooapis.com/v1/public/yql?format=json&q=' query = "SELECT * FROM weather.forecast WHERE location = " + response url = URI.encode(yahoo_url + query) json_data = open(url).read weather_data = JSON.parse json_data play 'temperature', weather_data["query"]["results"]["channel"]["item"]["condition"]["temp"] } </pre>

2009-03-05T01:43:04Z

36 19 Consuming the Yahoo Query Language

2009-03-05T02:07:15Z