Hacking Asterisk and Rails with RAGI

Hacking Asterisk and Rails with RAGI

by Joe Heitzeberg
12/19/2005

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:

• Mashing up RSS and voice to create a better kind of 411.
• eBay virtual call centers: High-volume seller and not around to answer your inquiries? Click to provision some virtual call center agents across the globe.
• Temporary phone numbers: Rent a temporary phone number for a week to use on Craigslist. Forward all calls to your real phone and log all messages on the Web.
• Click and talk with other people who are viewing a given web page.
• Learn Chinese: Fill out your profile, and we'll connect you with a qualified language instructor.

Joe Heitzeberg
Ruby on Rails with Asterisk

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:

• Start a consulting business installing 25-person office phone systems.
• Build the best home phone system ever. Calling China? Have the phone warn you, "It is 2 A.M. in China, are you sure you want to continue this call?" Away for the day? Have all your calls forwarded to your cell phone (unless they're from your employer; then play a Ferris Bueller movie audio clip).
• Build a banking IVR product to sell.
• Help your local politician get elected by auto-dialing a list of phone numbers and playing a message.

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.

Diagram Notes:

• You: Your Linux server is hosted on the internet, but instead of just serving web browsers, you also connect to phones and VoIP phones to serve mobile users, phone users, and VoIP users with voice interfaces.
• VoIP/PSTN service: Providers such as Level3 and GlobalCrossing and a multitude of smaller providers such as VoipJet, VoicePulse, and LES.net provide the capability to place and receive calls to regular phones via the internet (it's like SkypeOut, but from your server). Any mobile or land-line phone can be reached at very low cost.
• VoIP clients: Currently, Gizmo is the most open VoIP client out there, and the others (i.e. Skype and GoogleTalk) won't accept directly connected SIP traffic. However, as a workaround, you can connect to users of SkypeIn (the dotted line), or use Jabber for a limited interaction with GoogleTalk.

http://www.oreillynet.com/lpt/a/%3C%21--CS_NEXT_REF--%3E

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:

Diagram Notes:

• Phone calls come in to your Asterisk server, and control over how to handle the call (ask the user a question, play a sound) is handed to your web application server.
• Ruby on Rails is configured to load up RAGI when it starts, so that your calls have access to your entire set of classes defined in your web application (whatever you've built for user registration, data feeds, tagging objects, etc., will be available inside of the phone call session).
• A CallHandler subclass is created for every type of call session you might need (user checking account balance, checking voice mail, etc.).
• You can write services that handle incoming calls or place outgoing calls. Your only limit to capacity is bandwidth and CPU.

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

# when someone calls the number, 

# the call routes to this "dialup" method

def dialup

  answer()

    # 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.

    hangUp()

  end

end

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:

• Play sounds.
• Record sounds.
• Place a call (can be processed through RAGI when answered).
• Forward a caller to another number by placing a call.
• Listen for key presses (DTMF signals).
• Send key presses (DTMF signals).
• Text to speech.

Summary

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.