This is a guest post by Mark Silverberg (@skram on Twitter). Mark acted as a guinea pig for the Tropo Web API and Ruby library in the weeks leading up to its release last week. He wrote a sample app mashing up Twitter and voice and provided this overview and code walk through.

With Tropo’s newly released web API, developers can create unified communications (telephone, cellular text message, instant message (Jabber, AIM, Yahoo, MSN) applications using traditional document-based web development flow. The code gets stored on the developer’s choice of host and is referenced each time a call comes in (or is initiated using the Session API for outgoing phone calls). This additional approach to creating voice and IM-enabled applications allows developers to integrate Tropo code into their existing and new applications seamlessly, using their own hosting and servers. (The existing, hosted Tropo is still available.)

Here’s a twitter-by-phone example that uses the standard Twitter RSS feed for content, Sinatra as a web daemon (you could use rails or something else too) and the Tropo web (JSON) API. Since Tropo code is stored and run on the server of your choice, you can use any gems, custom classes, etc. to connect your data and content with phones and chat clients globally and on your own terms.

Instead of being a flat-file script with loops to validate input and drive the call flow with blocks of scripting logic, the JSON API with this shiny ruby gem allows for a document-based approach – like traditional web development. You can think of http://example.com/index.json, the URL you set as your Tropo App URL, as your website’s landing page. It is the first page/document ‘hit’ when a user calls your application.

Once the instructions in that document are finished, one of two Tropo API events are triggered (more about the code for this below): continue or incomplete. The events are triggered after the requested input is received (or not received). Example: If we ask for someone’s zip code, as soon as they say it, we continue to the specified next document. It’s as if, by saying, entering, or texting 5 numbers, the user has pressed the “Submit” button and they continue through your app to hear the weather, traffic conditions, tweets in proximity, what-have-you.

Making it all work together

Note, you could even integrate this right into your existing Sinatra/Rails/etc. web app. Just add a responds_to or document view for index.json, and put your Tropo code right in there. In the context of this Twitter example, I could have index.html be a HTML form asking for how many tweets the user would like to see at once, process.html be an intermediary view, and then page_of_tweets.html be, like it is in our voice application, a page-view of the number of tweets they requested. Your HTML page would have a “next” button for page, unlike the code published here which automatically reads the next page.

Before diving into the code (the version described below is in full here or the latest copy is available on GitHub), you may want to try this out for yourself. Call the @voxeo tweets by phone line at (253) 217-4272 or with Skype at +99000936 9991429531 for a demo. You can also create a Tropo app and point it to wherever you have hosted this web service. We deployed on Heroku for our demo, but you can use any Ruby web hosting you like.

As you’ll see, this code sample presents some number of tweets per ‘page’, defined by the caller. It will continue on to infinity, or however many tweets are available. As you step through the code, it may also be helpful to take a look at the more basic examples included with the Ruby library.

The call flow for this web service is quite simple. A call comes in and index.json is rendered.

post '/index.json' do

Sessions and Variables (twitter.rb, lines 5-9)

v = Tropo::Generator.parse request.env["rack.input"].read
session[:id] = v[:session][:id]
session[:caller] = v[:session][:from]
session[:user] = "voxeo"
session[:page] = 1  # This shouldn't be tinkered with unless you don't want the most recent tweets to be heard.

At one fell swoop, this web route collects the information Tropo sent the web service (like session ID, caller information, and timestamp) and stores relevant information into a session object Sinatra provides us for variable storage which will last the duration of the session. For this application, we’re storing the call_id and caller information information for debugging purposes. We also store the user we want to hear the tweets for here. Sessions are a convenient way to store not only caller information, but data we will want to use later in the call flow such as the page number of tweets we are reading.

Events (lines 11-14)

t.on :event => 'continue', :next => '/process.json'
t.on :event => 'error', :next => '/error.json'     # For fatal programming errors. Log some details so we can fix it
t.on :event => 'hangup', :next => '/hangup.json'   # When a user hangs or call is done. We will want to log some details.
t.on :event => 'incomplete', :next => '/incomplete.json'

On line 10, we initiate our Tropo::Generator object to which will append what we want Tropo to do for us. Lines 11-14 define our events for our index.json route. These tell Tropo what to do next, if there’s an error, if the user hangs up, or if the user doesn’t do what we expect them to do. As you’ll see at the beginning of the other routes, we want the same routes of error.json and hangup.json to be triggered for their respective events, so we repeat those lines.

Say & Ask (lines 15-22)

t.say "You have reached @#{session[:user]}'s tweets-by-phone."

t.ask :name => 'count', :bargein => true, :timeout => 7, :required => true, :attempts => 4,
    :say => [{:event => "timeout", :value => "Sorry, I did not hear anything."},
             {:event => "nomatch:1 nomatch:2 nomatch:3", :value => "That wasn't a one digit number."},
             {:value => "How many tweets do you want to listen to at once? Enter or say a one digit number."},
             {:event => "nomatch:3", :value => "This is your last attempt. Watch it."}],
              :choices => { :value => "[1 DIGITS]"}

Line 22 is the first thing the user hears. We welcome to our app and dynamically (because we stored the twitter username into our session hash) let them know whose tweets they are about to hear. Lines 17-22 are all for one Tropo action: ask. This block of code, which will be latter referenced as the action “count” prompts the user for how many tweets they will want to hear per proverbial page. It may seem weird that the actual question is sandwiched by events within the :say => [] block, but it’s actually very intuitive and conversation-like. When an event is matched (for example timeout, nomatch, or nomatch:#), the corresponding value will be said to the user before or after the question being posed. In this example, we sternly warn the user after 3 unmatchable responses that it’s their last chance after the question is repeated.

Continue: If the user inputs (here, they can speak a one-digit number or enter it using their telephone keypad) a valid answer to our question, the continue event will be triggered and the call continues.

Incomplete: If the user fails all four attempts we allotted them, they are transferred to the “incomplete” event we defined which in this case notifies them of what happened and terminates the call. Because we defined the hangup event again inside of incomplete.json, hangup.json (lines 69-74) will be executed once the call is terminated and Sinatra will print the information on the screen. For actual applications, this is where you’d probably want to log information for historical reporting and/or billing fun.

process.json (lines 40-49)

post '/process.json' do
  v = Tropo::Generator.parse request.env["rack.input"].read
  t = Tropo::Generator.new
    t.on  :event => 'error', :next => '/error.json'     # For fatal programming errors. Log some details so we can fix it
    t.on  :event => 'hangup', :next => '/hangup.json'   # When a user hangs or call is done. We will want to log some details.
    t.on  :event => 'continue', :next => '/say_page_of_tweets.json'
    session[:count] = v[:result][:actions][:count][:value]
    # t.say "@#{session[:user]} tweets coming right up!"
  t.response <br />
end

For calls that give us a one-digit number for the question we asked on line 17, we store that number into our session hash and send them to the next document which will read the tweets they requested.

say_page_of_tweets.json (lines 51-67)

post '/say_page_of_tweets.json' do
  t = Tropo::Generator.new
    t.on  :event => 'error', :next => '/error.json'     # For fatal programming errors. Log some details so we can fix it
    t.on  :event => 'hangup', :next => '/hangup.json'   # When a user hangs or call is done. We will want to log some details.
    t.on  :event => 'continue', :next => '/say_page_of_tweets.json'
    t.say "I'm about to read you the"
    t.say say_as_ordinal(session[:page])
    t.say " #{session[:count]} tweets by #{session[:user]}."
    source = "http://twitter.com/statuses/user_timeline/#{session[:user]}.rss?count=#{session[:count]}&page=#{session[:page]}"
    rss = REXML::Document.new(open(source).read).root
    rss.root.elements.each("channel/item") { |element|
      t.say "Tweet from about #{Time.parse(element.get_text('pubDate').to_s).to_pretty}"
      t.say reformat_uris(element.get_text('title').to_s) + "," # comma for extra pause between tweets.
    }
    session[:page] += 1
  t.response
end

This is where our application loops and reads the requested tweets one-by-one. This is the moment the session hash has been waiting for. We use the information we collected in index.json and process.json to report the requested information to the user.

Lines 61 through 64 is where we render the Twitter RSS feed we requested in line 60, and go through each tweet received to read the age of the tweet, followed by its content. As you can see on lines 57, 62, and 63, we use helpers whose code can be found in the accompanying goodies.rb file to present the data in a more user-friendly way.

At the end of each execution of say_page_of_tweets.json, as seen on line 65, we increment the session variable for page, so the next X-number of tweets are read when the action is re-executed (because, you guessed it, line 55 tells Tropo to execute that same document again).

Goodies.rb

As you can see on the first line of the script, we require()’d the ruby file goodies.rb. In it, I’ve provided some helpful methods for this particular app. I simply put them in a separate file so our main file is cleaner.

reformat_uris() removes the http[s]:// from URLs found in twitter status updates. We need to do this because Tropo handily (though not in this case) tries to stream URLs as sound files. This is very helpful when you want to play a MP3 file over the phone, but if you provide it a regular HTML site, it’ll synthesize it into white-noise.

say_as_ordinal() returns a string of VoiceXML. Tropo is built upon Voxeo’s highly tested infrastructure which, until now, has been mostly used for power and good of VoiceXML. Thankfully to use, Tropo stays true to its roots and allows us to execute VoiceXML. It can do a lot of handy things like turn “1″ into “first”, saving us from coding that conversion ourself and making sure it scales and is in correct English grammar.

to_pretty() is similar to the DateTime helper time_ago_in_words() available to Rails users. I found this method addition for the Ruby Time class and like it. As you can see, it’s very easy to customize too.

Conclusion

As you can see, this is a fairly basic application of a voice technology but it could be vastly expanded to become exponentially more feature-rich. For example, we could ask the user for more input such as giving them a choice of which twitter username to query, much more input validation, and more.

Tropo is backed by Voxeo’s extreme support. Check out Tropo’s contact page for all the ways to get help with Tropo and making the web applications you already have, and the ones you are only just now dreaming up, come alive with voice and IM-technology.