Tropo's cloud telephony services are absolutely awesome, and the fact that they make them available free to developers makes them an absolute haven for us to create weird telephony applications. I've recently been working on a wardialer using Tropo's cloud for a talk I'm giving at AdhearsionConf, and I thought I'd take a moment to explain how to work with the originate and recording functions when working with Tropo.

Initiating an outbound call with Tropo is actually a really simple process. After you create your Tropo application, you'll notice on your application page there's a voice outbound token assigned to your application. With that token in hand you can actually form a simple request to initiate the call.

res = Net::HTTP.postform(URI.parse('http://api.tropo.com/1.0/sessions'), "token" => @token, "destination" => number, "tropotag" => call_num)

In this case all I'm doing is using a simple POST to initiate a call via their API (acceptable parameters can be found here). The token field contains the voice token for your application, the destination field contains the number you wish to call (with country code), and in this case I'm also using the tropo_tag field to tag it with a unique identifier that I'll match on the adhearsion side when it comes time to actually control the call.

I've got my tropo application currently configured to use tropo-agitate to forward on control of the call to my adhearsion process (instructions for setting up tropo-agitate can be found here). So once the call is answered and control passes to my adhearsion process the first thing I want to do is begin to monitor the call (Warning: Recording calls may only be done with the consent of both parties in 12 states. In all other states, you only need the permission of one party, in this case yourself), so I'll send off off this little piece of code in my component:

num = JSON.parse(@call.tropoheaders)["tropotag"] res = @call.execute "startcallrecording", { 'uri' => "http://MYSERVER.com:3000/audio/#{num}", :method => "POST", :format => "audio/mp3" }.tojson

Here I'm pulling the tropo_tag out (the unique identifier I originally sent out), and then sending along the command to begin recording the call. Obviously since we don't have access to Tropo's servers, we have to have a way to get the audio afterwards, so you can either have Tropo FTP the file back to you, or provide it with an HTTP address to return the file to. In my case I felt like I'd have better control of my call's workflow if they sent it via an HTTP POST request (that way I can have rails throw it into the queue to be processed when it receives it). With that in mind I send it the address I want that POST request to go to in the uri field, along with the format (acceptable formats are audio/wav and audio/mp3).

Once your call is wrapped up, Tropo will transcribe that call into a temporary file and send it to the uri you specified beforehand. I haven't seen any way to force Tropo to name that file anything on it's return trip, or to include another tag, so this is where that unique id I assigned earlier came in handy. I was able to use it to form an id in the url that the audio is sent to. The file will come across as the 'filename' parameter in the post request, so to scoop it up, here's some simple file transcription code for your controller:

audio = params["filename"] name = "call#{params[:id]}.mp3" directory = "audiodata" path = File.join(directory, name) File.open(path, "wb") { |f| f.write(audio.read) }

This simply reads in the data in the POST and writes it out to a predetermined directory (in this case 'audio_data'). Keep in mind that this particular code does no checking on the incoming file to determine it's veracity, so if you're going to deploy something like this to production, you should verify that you're even waiting for a particular file, or risk people uploading malicious files to your server.

Anyways, that's the basic process I've used for placing and recording outgoing calls in my applications using Tropo. Hopefully this will help someone else in developing their own custom telephony applications.