Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Getting Started

JustinDupree edited this page · 15 revisions

Using Adhearsion with Asterisk

These are the high-level steps to get started with Adhearsion:

  • Install Asterisk
  • Install Ruby, RubyGems and Adhearsion
  • Create a new Adhearsion application
  • Optional: Configure your new application for AMI
  • Add stuff to dialplan.rb
  • Start your application
  • Call your application!

Installing Asterisk

Instructions to help install Asterisk can be found here

Installing Ruby, RubyGems and Adhearsion

Installing Adhearsion is very simple on all platforms. The Ruby language has an official package manager named RubyGems, which conveniently streamlines the installation of third-party software. Once you install Ruby and RubyGems, you can use RubyGems to install Adhearsion. Each operating system works with RubyGems, but with slight differences:

Mac OS X Leopard/Snow Leopard

Since you use Leopard, you already have Ruby and RubyGems installed! All you have to do is install Adhearsion using the gem command:

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.

Yep, that's it!

Mac OS X Tiger

We recommend installing Ruby and RubyGems together using MacPorts. MacPorts is a package manager for Mac OS X, similar to the package managers that come with virtually every Linux distribution. Download MacPorts from here and follow the installation instructions on the website.

MacPorts installs the port command; you'll use it to install Ruby and RubyGems:

sudo port install ruby rb-rubygems

Now, just install Adhearsion by doing

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.


On Linux, it's best to use your distributions's package manager to install Ruby and RubyGems, then have RubyGems update itself.

On Debian and Ubuntu, you can install Ruby and RubyGems this way:

sudo apt-get install -y ruby1.8-dev rubygems1.8   irb1.8 libsqlite3-ruby1.8

On the Red Hat variants such as RHEL, Fedora, and CentOS, run the following command:

sudo yum install -y ruby ruby-rdoc ruby-irb   ruby-sqlite3 

Updating RubyGems

Before we install any gems with RubyGems, let's make sure we're using the latest version. Upgrade RubyGems by running the following command.

sudo gem update --system

Now, we'll use the gem command to install Adhearsion:

sudo gem install adhearsion

This will automatically add the ahn command to your system, allowing you to create and start applications in the following step.

Microsoft Windows

On Microsoft Windows, you would install Ruby and RubyGems using these steps:

  1. Download and install the Ruby on Windows One-Click Installer (includes Ruby Gems)

  2. Open a Command Prompt and enter:

    gem install adhearsion

Note: Currently Adhearsion does not work as a Windows Service and therefore will only run interactively on Windows. It is on the roadmap to support a Windows Service in the near future.

For more ways to install Adhearsion (including how to get the latest-and-greatest code) see the Download page.

Creating and running your first application

Test that you have Adhearsion installed by running the following command:

ahn --help

This should print out the usage of the ahn command. This ahn command is the main way you create and run applications with Adhearsion.

Creating an application

Use the ahn command to create a new application in any directory you wish:

ahn create my_first_app

You will see the program print out a list of files it just created in the my_first_app folder.

Add content to dialplan.rb

Next, open the dialplan.rb file in your favorite text editor. This file contains the logic that is executed when you call into it. You should see something like the following:

adhearsion {

The name adhearsion in this file defines a dialplan context. The code within the curly braces is the implementation of the context. The simon_game text is a dialplan command or method. Methods often have arguments but the parenthesis around the methods are not required.

Next, to create a new context you'll add the following code to the bottom of your dialplan.rb file:

sandbox {
  play "hello-world"

We added a context named sandbox because this is where calls from into the sandbox will go. If you have other systems handled by this Adhearsion application, they can each go into their own respective Adhearsion context. In the sandbox context, you can also see the use of a dialplan method with arguments, in this case the string of text "hello-world" which corresponds to a sound filename on the sandbox server into which we'll now call.

Note: If you would like to access additional sound files beyond 'hello-world' , there's a listing of additional available sound files here.

Starting your application

Once you've done this, you're ready to start your application! Next, change back into the my_first_app directory and start it using this:

ahn start .

Where "." simply means the current directory. Alternatively, you can do...

ahn -

...which is a shortcut for starting the application in the current directory.

You should see Adhearsion output text as it starts the application.


That's it! Feel free to play around with your dialplan.rb file and add more code.

What you haven't seen yet

You just created your first Adhearsion dialplan but there's much more to Adhearsion than the dialplan! Here is a cursory overview of what you haven't seen yet:

Using and writing Adhearsion components

Adhearsion components are plugins which you can install into your individual application.

Calling real telephones

Handling realtime events

Integrating with a database

Here are a few ideas to explore further:

  • Try invoking the simon_game method that came with in your dialplan. Hint: it's a memory game.
  • Try out some of the Examples.


Something went wrong with that request. Please try again.