Sophisticated Asterisk Development with Adhearsion
Pages: 1, 2, 3, 4

Ruby/RubyGems on Windows

A fantastic "one click installer" exists for Windows. This will automatically install Ruby, RubyGems, and a few commonly used gems all in a matter of minutes. You can download the installer from http://rubyforge.org/projects/rubyinstaller.

Installing Adhearsion from RubyGems

Once you've followed one of the instructions above for your system to fetch Ruby and RubyGems, install Adhearsion with the following command:

gem install adhearsion

Exploring a New Adhearsion Project

With Adhearsion installed, you can begin creating and initializing a new Adhearsion project with the newly created ahn command, a command-line utility that manages nearly everything in Adhearsion.

An example command for creating a new Adhearsion project is as follows:

ahn create ~/newproject

This creates a folder at the destination specified containing the directory and file hierarchy Adhearsion needs to operate. Right away, you should be able to execute the newly created application by running:

ahn start ~/newproject

To familiarize yourself with the Adhearsion system, take a look through the application's folders and read the accompanied documentation.

Adhearsion Dial Plan Writing

The ability to write dial plans in Adhearsion is often the first feature Adhearsion newcomers use. Because Ruby permits such fine-grained modification of the language itself at runtime, Adhearsion makes aesthetic changes to streamline the process of developing dial plans.

Below is an Adhearsion Hello World application.

my_first_context {
  play "hello-world"
}

Though this is completely valid Ruby syntax, not all Ruby applications look like this. Adhearsion makes the declaration of context names comfortable by interpreting the dial plan script specially. The dial plan script is located in the root folder of your newly created Adhearsion application.

As calls come into Asterisk and subsequently Adhearsion, Adhearsion invokes its own version of the context name from which the AGI request originated. Given this, we should ensure a context in extensions.conf has this same name and forwards calls properly to Adhearsion.

The syntax for directing calls to Adhearsion is as follows:

[my_first_context]
exten => _.,1,AGI(agi://127.0.0.1)

This catches any pattern dialed and goes off to Adhearsion via AGI to handle the call processing instructions for us. The IP provided here should of course be replaced with the necessary IP to reach your Adhearsion machine.

Now that you have a basic understanding of how Adhearsion and Asterisk interact, the following is a more real-world dial plan example in Adhearsion:

internal {
  case extension
    when 10..99
      dial SIP/extension
    when 6000..6020, 7000..7030
      # Join a MeetMe conference with "join"
      join extension
    when _('21XX')
      if Time.now.hour.between? 2, 10
        dial SIP/"berlin-office"/extension[2..4]
      else speak "The German office is closed"
      end
    when US_NUMBER
      dial SIP/'us-trunk-out'/extension
    when /^\d{11,}$/ # Perl-like regular expression
      # Pass any other long numbers straight to our trunk.
      dial IAX/'intl-trunk-out'/extension
    else
      play %w'sorry invalid extension please-try-again'
  end
}

With just this small amount of code we accomplish quite a lot. Even with limited or no knowledge about Ruby, you can probably infer the following things:

• We use a switch-like statement on the "extension" variable (which Adhearsion creates for us) and branch depending on that.
• Dialing a number between 10 and 99 routes us to the SIP peer with the dialed numerical username.
• Any number dialed between 6000 and 6020 or between 7000 and 7030 goes to a MeetMe conference of that same number. This of course requires meetme.conf to have these conference numbers configured.
• The _('21XX') option comes straight from Asterisk's pattern style. Prepending a String with an underscore in Adhearsion secretly invokes a method that returns a Ruby regular expression. In a Ruby case statement, regular expressions can be used in a when statement to check against a pattern. The end effect should be very familiar to those with extensions.conf writing experience.
• Adhearsion's syntax for representing channels also comes straight from Asterisk's traditional format. SIP/123 can be used verbatim to represent the SIP peer 123. If a trunk were involved, SIP/'trunkname'/'username' would act as you would expect.
• The speak() method abstracts an underlying text-to-speech engine. This can be configured to use most of the popular engines.
• A full blown Perl-like regular expression can be used in a when statement to perform more sophisticated pattern matching if Asterisk's patterns do not suffice.
• Adhearsion defines a few constants that may be useful to someone writing dial plans. The US_NUMBER constant here is a regular expression for matching an American number.
• If you find the need to play several files in sequence, play() accepts an Array of filenames. Luckily, Ruby has a convenient way of creating an Array of Strings using the %w"" syntax.

This is of course just a simple example and covers only the absolute basics of Adhearsion's dial plan authoring capabilities.

Pages: 1, 2, 3, 4

Next Page