Making phones ring with Tropo

May 3, 2011

Uncategorized

If you ask Adam Kalsey what Tropo is he is very quick to reply “Write a line of code, make a phone ring.” I heard that at least a hundred times Saturday. I probably need to explain that Tropo’s boot is always one of the most popular at any show. Not because Adam gives away T-Shirts but because he gives away very cool looking T-Shirts. Not your usual conference T-Shirt fare. So during the course of the day, EVERYONE comes up and asks what Tropo is. Most listen politely for a few seconds and then ask for a T-Shirt. You can always tell the developers in the crowd because the API is more interesting that the swag to them.

I sat down yesterday to play with Tropo’s API and see what all the fuss was about. An hour or so later, I was actually making my phone ring.

First Steps

As with any good API, the first steps are to register for an account. Once you have an account, you can create applications. I should note that the example I will be showing here is the equivalent of “Hello World”. It is brain-dead simple and kind of stupid but it let me play with the moving parts. I wanted to write an application that would call a number and tell them something. In my mind, the real-world example of this would be using it to hook into monitoring systems to have the system call me when a server’s load gets too high, or my inventory levels are below a set point. However, demos are never the real world so I decided to have it call the Lovely and talented Kathy and tell her how much I love her.

WebAPI vs. REST API

Before I could write my application though, I had to decide, WebAPI or REST API. If you look at the home page of the Tropo Docs this is a choice presented to you. This was my first point of confusion. For better or for worse, REST, in my mind, is tied to the web. Therefore asking me if I wanted Web or REST seemed like asking me to choose between paints colored “Egg shell” and “White”. It took a bit of digging around to figure out exactly what the difference was. WebAPI is what you want if you want to use their PHP library to write code that runs on your server, talks to Tropo, and makes things happen. Before you nod knowingly and decide that this is what you want, think it through. Latency is a fact of life on the web, but not on the phone. If your app has decisions that need to be made during the call, latency can make the difference between a positive customer experience and a negative one. Granted, the “Hello World” I am showing here could have easily been written using WebAPI. However, I chose the easier of the two, REST API combined with Tropo hosting my files.

The code that rings the phone

<?php
_log('Number To Call:'.$numToCall);
_log('Payload:'.$payload);
call('+'.$numToCall);
say ($payload, array('voice'=>'veronica'));
hangup();
call('+16155551212',array('network'=>'SMS'));
say('I sent a message to '.$numToCall.' saying '.$payload);
?>

As you can see, the code is a bit more generic than just call a specific number and give a canned message. This file is actually hosted on Tropo’s servers. As you can see, for the most part, it is straight PHP. There are a couple of things you need to know up front though that I didn’t easily find. First, _log(). is your friend. it's the Tropo equivalent of var_dump(). Anything you need to take a look at, you can _log(). As you can see, I am dumping the two parameters passed into the script, $numToCall and $payload. While this is interesting, the logger already logs the variables and their contents as it instantiates them. Anything you _log() shows up in the application debugger.

The application debugger is a page that just shows the progress of the application. As with any debugger, it gives you a lot of info to sort through including, as mentioned above, when parameters are instantiated and their initial values. The _log() function will be much more useful to larger applications that need to monitor things as they progress.

Second, you have probably noticed $numToCall and $payload. These are parameters passed in on the GET and automatically created for me. This is true of parameters passed in via GET or POST. I've not played enough yet with the hosted apps to determine whether $_GET and $_POST are supported or if the variables are all we get.

One cool thing is that the say() command has "voices" that you can choose. The voices range in pitch from female to male and speak the text in several different languages.

Actually making the phone ring

Once you have that simple little script in place, it's just a matter of making the right API call. Here Tropo's developer site really shines. When you go to your application's page, you see your secret keys. Clicking on the key brings up a window that allows you to copy the entire URL for later use or to launch the URL.

In my demo application, the url looked like this:


https://api.tropo.com/1.0/sessions

?action=create
&token=none+of+your+business
&numToCall=16155551212
&payload=Cal%20Loves%20you%20very%20much

Copying the URL and pasting it into a browser will execute it and show you the XML payload. If you have the Tropo Debugger application running, you can see the progress of the script. You can't stop it while it's running but you can scroll up and down in the log to see what went on.

The last thing the script does is send me a TXT message telling me who it called and what it said to them. I did this to move a little beyond the cut and paste from the docs. I quickly found out that to start another call, you have to issue a hangup() first. Something the Docs don't really spell out but its common sense if you think about it.

Problems

Most of the problems I had with the API dealt with my misunderstanding what was going on and how things worked. There were a couple of things I never did get working but I am sure given time I could figure them out too. An example is that the call() method takes as a parameter callerID The docs say that this can be any valid phone number, however, anything I specified was ignored and it defaulted to the number Tropo gave me. Interestingly though, if I didn't specify a callerID my phone showed "UNKNOWN".

The docs did have all the information I needed but I had to jump into the Forums to actually find pointers to some things. The upside s that they seem to have a good forum staff that answer questions quickly. Because they support so many languages, the docs seem to be the lowest common denominator. Things that I think are important aren't really specified. For instance, I have seen examples where the call() method returns a "call object". What is unclear is whether this is in the hosted environment or just in their PHP library. The documentation doesn't really tell you (that I could find) all the details about the hosted environment like what PHP extensions 9if any) are supported, etc. If you read the Tropo Application Debugger - especially if you hit a bug - you quickly discover that the PHP is being converted into Java. While this isn't really a problem, it is not clearly explained and therefore PHP developers don't know what is going on and what is available to them.

Another issue I had and the documentation wasn't very really clear on is whether or not you have to include "Basic HTTP Authentication" in your REST API calls. The tests I did required it but that may have been because they were operating in the development environment. It isn't a problem to include Basic Auth in a call via PHP but it is something you need to know ahead of time.,

End things on a high note

There is a lot to love in Tropo for PHP developers, the best thing though is their attitude. If you talk to Adam about their developer program, he'll tell you something along the lines of "Use it until you move your code into production; then come talk to us about billing." I play with a lot of APIs and each of them has various restrictions on development use. Tropo seems to operate on the honor system. They trust you that the calls you are making are necessary for testing and unless you abuse the privileged, they let you keep going.

Tropo USB KeyIf you've been looking for something to allow you to integrate Voice or SMS into your application, Tropo is a good place to start. If you have been looking for a new toy to play with Tropo is a new shiny. It has so many options and features that just spending a few hours playing with it will spark new ideas. If you are lucky enough to see them in person at a conference, ask for one of their cool t-shirts. They also have "other" swag on hand from time to time but because of how popular it is, they don't often advertise they are available. However, if you ask, they may be able to find you one.

About Cal Evans

Many moons ago, at the tender age of 14, Cal touched his first computer. (We're using the term "computer" loosely here, it was a TRS-80 Model 1) Since then his life has never been the same. He graduated from TRS-80s to Commodores and eventually to IBM PC's. For the past 10 years Cal has worked with PHP and MySQL on Linux OSX, and when necessary, Windows. He has built on a variety of projects ranging in size from simple web pages to multi-million dollar web applications. When not banging his head on his monitor, attempting a blood sacrifice to get a particular piece of code working, he enjoys building and managing development teams using his widely imitated but never patented management style of "management by wandering around". Cal is currently based in Nashville, TN and is gainfully unemployed as the Chief Marketing Officer of Blue Parabola, LLC. Cal is happily married to wife 1.28, the lovely and talented Kathy. Together they have 2 kids who were both bright enough not to pursue a career in IT. Cal blogs at http://blog.calevans.com and is the founder and host of Day Camp 4 Developers

View all posts by Cal Evans

Comments are closed.