Getting Started

Because Adhearsion is a framework for writing telephony applications, it depends on a bit of lower-level plumbing to get an application running. We want everyone to easily give Adhearsion a try so we've set up a completely free sandbox telephony system which allows you to use Adhearsion without setting up Asterisk. You won't be able to dial out to landline and cell phones but you will be able to get a good idea of what Adhearsion is and how it works.

We'll go into these steps in more detail but, at a high level, this is all that is required to use the sandbox:

• Sign up for a sandbox account on this webpage
• Install Adhearsion
• Create a new Adhearsion application
• Enable the sandbox component with your new application
• Configure it with the username and password you used for your sandbox account
• Start your application
• Use a Voice over IP softphone to call your unique VoIP extension

Firstly, if you don't have an account yet, sign up for one with the form on this page. The rest of the instructions assume you already have an account.

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, we'll use RubyGems to install Adhearsion.

Choose one of the operating systems below for installation instructions.

sudo gem install adhearsion

sudo port install ruby rb-rubygems

sudo gem install adhearsion

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

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

sudo gem update --system

sudo gem install adhearsion

gem install adhearsion

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.

Enabling and configuring the sandbox component

Next, we need to enable the sandbox component so that your application can accept calls when you call in with a PC phone. To do this, enter the following commands:

cd my_first_app
ahn enable component sandbox

Components are like plugins to an Adhearsion application. They extend your application with some unit of functionality that is unique only to the individual applications that have installed and enabled it. New Adhearsion applications come with a number of components enabled and disabled. You can view the pre-installed components by looking at the folders in the components directory. The components/disabled folder contains components which are presently disabled. You can disable the component later by doing

ahn disable component sandbox

or by moving the components/sandbox folder into the components/disabled folder.

Now that the sandbox component is enabled, we need to configure it with your username and password. Doing this is very easy. Open the components/sandbox/sandbox.yml file in your favorite text editor. It will look like the following:

username: lordxenu
password: iamthegalacticrooolah

Replace user123 and pass123 with the username and password you gave the signup form on this page. Adhearsion uses the very clean and readable YAML markup language (file extension .yml) for virtually all of its configuration.

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 by doing

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.

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 {
  simon_game
}

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.

We are now going to create a new context, 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' you have a full listing of available sound files here.

Calling into your application.

Now that you've written an application, let's test it! There are four ways you can do this:

• With your normal cell or landline phone
• Using Skype
• Using an in-browser phone
• Using the SIP VoIP protocol with SIP software

Calling in with your cell or landline phone

For those that have never done telephony development before, calling in with an actual phone will feel most satisfying and exciting.

The folks over at Voxbone have dedicated a public number for the sandbox into which anyone can dial. At the moment it supports only ten concurrent calls so it's possible that you'll get a busy signal when a lot of people are using it.

When your Adhearsion application is running with the sandbox component enabled, call into the following number and enter your PIN.

+1 (213) 325-2621

To get your PIN number, create an account. Your PIN number will be emailed to you and can be viewed on the Manage Account page when you're logged in.

Using Skype (BETA)

Skype recently seeded out a new beta release of their Asterisk extension that enables Skype interoperability. Tough we can't assure we'll have this forever, you can certainly use it to test your application using Skype's great softphone.

Note: The Skype for Asterisk channel driver is still beta software is sometimes must be disabled because it crashes Asterisk altogether. If the Skype gateway is down, this is probably why.

For Skype, we have to handle calls to the sandbox a bit differently. Because we can't take over your Skype account or register arbitrary accounts for you, you will have to call into our sandbox's Skype account and our server will have to convert the incoming call's Skype username (your username) to your respective sandbox username so it can find your running Adhearsion app. For this reason, you'll have to enter your Skype username on the Manage Account page if you already haven't.

Therefore, the steps are:

• Register a Skype account if you haven't already
• Register a sandbox account and give it your Skype username
• Run your sandbox-enabled Adhearsion app
• Call into sandbox.adhearsion.com

Using an in-browser phone

Tim Panton of the Phone From Here project generously built a custom version of Phone From Here that will work with the Adhearsion sandbox.

After you create a sandbox account you can find a Phone From Here phone on your Manage Account page but, if you already have an account, you can enter the username below.

If you have any issues with Phone From Here, please report them.

Using the SIP VoIP protocol

If you're most comfortable with using a good ol' SIP softphone or physical desktop phone with the sandbox, it's extremely easy to do. The only requirement is that the SIP implementation used conforms well enough and sends the SIP "To" header properly.

If you don't have a preferred SIP softphone, we recommend Gizmo5. Though Gizmo5 requires you to register a Gizmo account, it does this so it can more easily bypass firewall issues that typically plague SIP.

To get up and running with Gizmo5, visit their website and follow their instructions.

Now that you have your SIP phone ready, simply call xyz@sandbox.adhearsion.com, replacing xyz with your sandbox account username. SIP URIs typically look like email addresses.

Conclusion

That's it! Feel free to play around with your dialplan.rb file and add more code. The sandbox is here for you to play with to your heart's content.