Published on O'Reilly (http://oreilly.com/)
 See this if you're having trouble printing code examples

Hacking Asterisk and Rails with RAGI

by Joe Heitzeberg

Chances are that by now you are using Skype, Yahoo Instant Messenger with Voice, Google Talk, or one of the other PC VoIP phones that let you talk for free over the internet. You might also be a customer of Vonage, AT&T CallVantage, BroadVoice, or one of the other VoIP-based land-line replacements that give you flat-rate, unlimited calling and tons of great features like voicemail-to-email or click-to-call.

Thanks to VoIP, now anyone can talk for free; I get that. But what's next? Free calls and voicemail-to-email are just the beginning, right? You bet! Open protocols, low telephony cost, and a rapidly growing installed base of VoIP-capable PCs, phones, and networks mean a wave of innovation and opportunity, and we're just at the beginning.

In this world, hackers and entrepreneurs everywhere ought to be able to pioneer vastly new and powerful services, such as:

Joe Heitzeberg
Ruby on Rails with Asterisk

O'Reilly Emerging Telephony Conference 2006

O'Reilly Emerging Telephony Conference
January 24-26 2006
San Francisco Airport Marriott

You might have read about Google's latest foray into "Click to Dial" advertising. There is no reason you can't build a similar service.

In this article, I'll provide a quick overview of how Asterisk, the open source PBX, can be used as a general-purpose "telephony protocol server," and can be connected to Ruby on Rails to create a rapid prototyping environment for creating next-generation VoIP applications and services.

Asterisk in 30 Seconds

Asterisk is an open source PBX. It is designed to handle all of the basic office phone services an ordinary PBX might handle and more, including call routing, conferencing, call forwarding, and three-way calling. It also speaks more than half a dozen VoIP protocols and codecs, and runs on Linux. You might use Asterisk to:

Ruby on Rails in a Jiffy

If you are building web apps, then you might consider running (don't walk) to get yourself outfitted with Ruby On Rails, a great new web-application development framework by David Heinemeier Hansson and many open source contributors. Rails is framework for creating database-driven web sites that manages to cut out a lot of the grunt work typically associated with Java- or Perl-based frameworks. Rails uses the Ruby language, which will feel familiar to any Java or C# programmer, and includes tons of libraries to help with common web development tasks and with newer things like Ajax.

Bird's-Eye View

Hopefully you are starting to get the picture: hosted VoIP-enabled apps that connect to VoIP phones like Skype and real phones, and operate on the same kind of open source development stack that powers the Web. Say goodbye to proprietary and closed telephony hardware and hosted voiceXML platforms that tie you to someone else's voice platform. Plug a Linux box into the internet, grab a domain name, and get in business.

figure 1

Diagram Notes:

Rails + Asterisk = Peanut Butter + Chocolate

What could be a better way to create these new apps and services than to combine Asterisk's VoIP handling capabilities with the power and efficiency of Ruby on Rails?

For that purpose, we have RAGI: Ruby Asterisk Gateway Interface. RAGI is a simple API and set of helper classes that facilitate programmable phone logic, or IVR, from a Ruby environment by implementing the Asterisk AGI protocol. In Rails apps, RAGI makes handling phone call interaction something similar to rendering a web page. From a systems point of view, it allows you to attach your Asterisk server to your Rails server something like this:

figure 2

Diagram Notes:

Programming with RAGI

With RAGI, you spend most of your time focusing on application logic and you get full access to the objects and services you've already defined for the rest of your web application. Spend less time hacking low-level Asterisk and VoIP configurations, and more time on user experience!

Let's take a look at the body of a call handler to get a sense of what this looks like:

module MyCallHandler
  class CallHandler < RAGI::CallHandler

# when someone calls the number, 
# the call routes to this "dialup" method
def dialup
    # Who is calling?  Read the caller id
    user_phone_number = @params[RAGI::CALLERID]
    # Look up the user in the db using Rails.
    # Since the db has a "phone_number" field, Rails
    # automatically provides a "find_by_phone_number" method
    # on the User class -- gotta love Rails!
    user = User.find_by_phone_number(user_phone_number)
    # Service logic here...
    #    if (user.account_balance <= 0) --> hangUp
    #    else --> speak "hello" + user.first_name
    #    Play their voice mail
    #    Ask for key presses
    #    Connect this call to conference call
    #    Etc.

RAGI exposes most of the major functions and capabilities of Asterisk itself. And if what's already there is not enough, you can add and contribute back, since RAGI is open source. The major API functions are:


VoIP connectivity has quickly become ubiquitous. Its openness and low cost means that it can be combined with traditional web infrastructure to create powerful new communications applications and services. In this article, I've sketched out what those new services may look like, and illustrated an approach to developing such applications using open source software such as Asterisk and Ruby on Rails.

Would you like to learn more?

I'll be doing a workshop on RAGI at the O'Reilly Emerging Telephony conference, January 24 to 26 in San Francisco. Also, in the new year, look for a complete tutorial on O'Reilly about using RAGI. In the meantime, please feel free to get started on your own by visiting the RAGI developer pages.

Joe Heitzeberg is founder of SnapVine, Inc., a pioneering mobile voice applications startup.

Return to O'Reilly Emerging Telephony

Copyright © 2009 O'Reilly Media, Inc.