Cloudvox: Cloud Telephony Applications Made Easy

A couple of months ago, I did a quick write up on a new cloud telephony company named Cloudvox. In the interim, I’ve been doing some playing around with their HTTP/JSON API for creating telephone applications, and I’ve been blown away by how simple and powerful a tool it is for building sophisticated cloud telephony applications.

This post will provide a quick overview of how the Cloudvox JSON API can be paired with PHP and the delightfully awesome Limonade Framework. If you’re not a PHP developer don’t despair – this example can easily be ported to other languages like Ruby (using Sinatra) or C# (using Kayak).

Cloudvox API Helper Classes

When writing apps for the Cloudvox JSON API, there are two things that we need to manage – the JSON that we will send to Cloudvox (using plain old HTTP) and the response Cloudvox sends back to our app (this will include any user input collected from the caller, and also things like a unique identifier for the call, caller ID and other information about the call).

To make managing both sides of our exchange with Cloudvox easier, I’ve created a set of PHP classes that can be used with any standard PHP IDE to make writing Cloudvox JSON and parsing Cloudvox responses simple and easy. You can download this class library from GitHub.

Using these classes is pretty straightforward:

Will render:

[{"name":"Speak","phrase":"Hello world!"},{"name":"Hangup"}]

Required properties are included in the constructor for each class – in most IDE’s this means that you can simply use Shift + Control + Space Bar when you create a new instance of the object to see what properties are required.

Optional properties on all classes are handled by using the PHP __set() method in the base class. This effectively let’s you overload the object and set properties which are not declared in the class definition. So for example, if we wanted to collect input from the caller (e.g., their zip code) we would use the GetDigits class, and overload it to add a URL to post the results to:

url = "";


The problem with overloading in PHP is that you don’t get the benefit of having your IDE display overload options (it can’t because the properties that we wish to set are not declared in the class definition). There also isn’t any way to control what overloaded properties get set, so its possible to add things the Cloudvox won’t understand.

I’m not sure there is any way around this given the way that PHP has implemented overloading. I do plan to work on a set of Cloudvox classes using another language that handles overloading a bit better, like C#, but for now you should only overload to set the url and method properites for classes that can use them (see the Cloudvox docs for more details).

Sipping on some Limonade

If you know of the excellent Ruby Framework Sinatra but you want to code your project in PHP, fear not – check out the equally excellent PHP framework called Limonade. It’s the functional equivalent of Sinatra for PHP.

Using Limonade with our set of Cloudvox JSON classes makes building cloud telephony applications very simple. The biggest benefit is that you don’t have to split up the different steps in your application (i.e., collecting input, validating input, re prompting, etc.) into different PHP files (which can be kind of a pain) – all of your steps can be contained within a single file.

Limonade lets you set a URL “route” that Cloudvox can send HTTP requests to with results, and to get rendered JSON for another application step. For example:

This “Hello World” example – defined in a script named sample.php – could be accessed by hitting To make things easier, we’ll use a little Apache magic to allow URL rewriting:

This will let us access the above URL by hitting

A simple demo app using the Cloudvox JSON helper classes and the Limonade Framework can be seen below. You can use this sample application with a new Cloudvox account to get started building cloud telephony applications.

This simple app demonstrates how powerful the Cloudvox JSON API is for creating cloud telephony apps. When coupled with an elegant framework like Limonade, sophisticated, cloud-based telephony applications are readily available to any developer that wants to build one.

The helper classes for the Cloudvox API are obviously a work in progress, so if anyone reading this has comments or suggestions feel free to let me know – mheadd [at]


XHP for VoiceXML

Facebook has been busy lately doing all sorts of interesting things to the PHP scripting language. Although most of the recent PR hype was centered around HipHop for PHP (a name that, quite frankly, makes me want to use it less), Facebook also released another very interesting and potentially useful extension for PHP – XHP. From the XHP wiki on Github:

XHP is a PHP extension which augments the syntax of the language such that XML document fragments become valid PHP expressions. This allows you to use PHP as a stricter templating engine and offers much more straightforward implementation of reusable components.

Not sure where I read it, but one commenter compared XHP to E4X in JavaScript. It’s a neat idea, and its actually not all that hard to start playing around with XHP (if you’re comfortable installing PHP extensions).

After thinking about XHP and playing around with it a bit, I started to think it might be useful as a way of generating not just HTML, but also other XML-based languages like VoiceXML.

The core XHP classes that are used for generating HTML are fairly easy to understand, once you get use to the syntax – extending these core classes to generate VoiceXML (or any other XML-based language) is not all that hard. But before we do that, let’s install XHP as a PHP extension and kick the tires a bit.

Installing XHP on Ubuntu

I’ve tried the following instructions on both Ubuntu 8.04 and 8.10, and I’m pretty sure they’ll work with just about any recent Ubuntu version.

Make sure you’ve got the basics for building PHP extensions:

$ sudo apt-get install build-essential
$ sudo apt-get install php5-dev

Get the XHP source code:

$ mkdir xhp
$ cd xhp
$ git clone git://

Get the PHP source code

$ sudo apt-get source php5

Make a directory in the PHP source code for the XHP extension

$ mkdir php-5.X.X/ext/xhp
$ cp -r xhp/xhp/* php-5.X.X/ext/xhp/

Depending on your system, you may need to add some of the prerequisites for building this extension:

$ sudo apt-get install flex bison

I tried this approach on both Ubuntu 8.04 and 8.10 and in both cases only version 0.13.5 of re2c worked (earlier version obtained via apt-get did not cut the mustard). If you’re running a later version, you may be able to get this version of re2c from the standard repos.

For this example, I’ll just build it from source:

$ wget
$ tar -zxvf re2c-0.13.5.tar.gz
$ cd re2c-0.13.5/
$ ./configure
$ sudo make
$ sudo make install

Move to new XHP extension directory and get ‘er done.

$ cd php-5.X.X/ext/xhp
$ phpize
$ ./configure
$ sudo make
$ sudo make install

When you run make install, the new extension file is placed in a directory where Apache can load it – however, we need to modify the php.ini file so that Apache is aware of the extension. Open php.ini and add the following:

When setting this last option, use the directory where was placed by make install. Now we just restart Apache:

$ sudo /etc/init.d/apache2 restart

Easy right? Unfortunately, things get a little less clear at this point. It turns out that to make XHP work properly, some PHP libraries need to be included in any of the XHP scripts we write. These files are located in the php-lib directory of the XHP source code.

To make things easier (especially when we start to write our own extension to XHP for VoiceXML, lets move these files to a convenient local directory that we can include in our scripts:

$ cp php-5.X.X/ext/xhp/php-lib/* my/local/directory/php-lib/

So now we can do some interesting stuff like this:

What’s especially interesting about XHP is that it enforces proper syntax at compile time, so if your markup isn’t syntactically correct an exception gets tossed.

Generating VoiceXML with XHP

The XHP libraries we just discussed implement the HTML spec out of the box. However, if you try and render tags that are not part of the HTML spec an exception will occur. I wanted to find out how hard it would be to extend the concepts behind XHP for other markup languages, like VoiceXML. Turns out, its not hard at all.

If you look at the init.php file that is included in the example above, you’ll see its in turn including a file called html.php, which defines all of the HTML elements that can be rendered by XHP, the attributes that each can have and also the parent-child relationship between elements.

Using this is a guide (the syntax is new but fairly easy to follow), I knocked out a quick class file for some basic VoiceXML elements – just to illustrate the concept:

This is admittedly rough, and it only covers a few basic VoiceXML elements, but it demonstrates that extending XHP to render VoiceXML is actually quite easy. To use this file, simple edit the init.php file mentioned previously and add an include statement:

Now we’re ready to use XHP to generate VoiceXML:

How cool is that?

I’m still toying around with XHP, but this little experiment clearly shows that it has use beyond just simply rendering HTML. I’d be interested in hearing from other developers – is this worth a full blown project to flush out a complete VoiceXML class library for XHP? What other markup languages would make good candidates for this same type of approach?

Post a comment here, a tweet to @mheadd or shoot a quick e-mail to mheadd [at] with your thoughts or comments.