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.
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,
$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
$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.
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.
If 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.