Plugin to interact with the Tropo Cloud platform

Summary

Installation

grails install tropo-webapi-grails

Description

Description

Tropo is an Open Source massively scalable developer platform that makes it simple to quickly and easily build phone, SMS and Instant Messaging applications - or applications that handle all three - using the web technologies you already know and Tropo's powerful cloud API.

This plugin implements the Tropo WebApi which is a server-side API that allows developers to create with very few lines of code applications that can send and receive SMSs and calls, build instant messaging powered applications, build conferences, transfer calls, record conversations, play and send sound files to other people and many other cool things. Apart from the Tropo WebApi, this plugin also implements the Tropo REST API which is a provisioning API that lets you configure, launch and manage all your Tropo applications.

To run your Tropo applications you will need a Tropo powered application server. Voxeo (Tropo authors) offers the Tropo Cloud platform which is totally free for developers and which has very competitive rates for production deployment.

Requires

Grails 1.0.5 or higher.

Includes

commons-codec-1.3.jar

ezmorph-1.0.6.jar

http-builder-0.5.1.jar

httpclient-4.0.3.jar

httpcore-4.0.1.jar

json-lib-2.4-jdk15.jar

xml-resolver-1.2.jar

Installation

You can install this plugin by running the following command:

grails install-plugin tropo-webapi-grails

Screencast

Be sure to check out this screencast on how to create your first project with Tropo and Grails: http://blog.tropo.com/2011/04/20/voice-powered-applications-with-grails-screencast

5 minutes tutorial

In the following sections we will create a sample Grails application that uses Tropo services. It will take you less than 5 minutes.

Creating your Tropo application

Once you have the plugin installed you will find that creating voice and SMS powered application becomes incredibly easy. But first of all you need to sign up with Tropo. Once you have registered and signed in you can proceed and create your first application. As we are creating an application that uses the WebApi, you need to click on the plus button and then choose WebApi application like in the picture below:

Tropo applications can be executed in very different ways. Whenever a tropo application is launched the Tropo Cloud platform will create a new session and will invoke an URL at your server. Tropo applications can be triggered in many different ways like for example:

Calling a phone number that you have set up

Calling a skype number

Sending a SMS

Sending a message through an IM network

Using the REST API

From Grails itself using the TropoService object (effectively it runs a GET request to the REST API)

Therefore, the next step you need to do is to define the URL at your server that will be invoked when a new session is launched from your Tropo application. The next picture shows how I pointed my newly created Tropo application to my Grails instance:

Once the application is created you will find that there is already several phone numbers linked to it. There is already a Skype phone number and you can link your application with several IM networks or even your Twitter account. On that same screen you will find links to attach new US national and international phone numbers to your application. More than 40 countries are supported. A mesage or phone call to any of these phone numbers or services will trigger your Grails controller logic. In the screenshot below you will find that I have attached an US national number and an UK phone number to our sample application:

Creating your Controller

Once your application is created adding voice support to it is really simple. You do not need any specific artifacts so you can add voice and messaging support to any of your Grails controllers, services or Taglibs. However, you will need to provide some implementation for the Grails controller that you have linked to your application in the previous steps.

The Tropo WebApi is based in JSON and defines many different methods. This plugin provides a groovy builder that makes really easy to interact with the Tropo platform. Below you can find an example for our TropoController.groovy:

Note that you can also use a more 'traditional' approach. The following source code is equivalent to the snippet above. Use whatever syntax you feel more comfortable with.

import com.tropo.grails.TropoBuilder;

class TropoController {

def index = {

def tropo = new TropoBuilder()

tropo.say("Hello World. Hello Tropo. We are going to play a song.")
tropo.say("http://ccmixter.org/content/copperhead/copperhead_-_When_We_Do.mp3")
tropo.hangup()

tropo.render(response)
}
}

Testing your application

If you have created some landline phone numbers you can test your application just by calling those phone numbers. For example, in this tutorial you could call either +44 1259340253 or (407) 680-0744 and you would hear a welcome message and a mp3 song would be played until either the song stops or you hang up. You can also use Skype to call your application:

And that is it. As you have seen, we have created a Grails application that answers a phone call and plays some song to the user with almost no effort. This is a very naive example but it shows how easy this plugin makes to add voice and messaging to your apps. Now it would be a nice moment to stop and learn more about the Tropo WebApi reference and all the possibilities that brings up to developers.

In the sections below we would expand on this plugin and will provide samples about how to call all the different methods.

Source Code

Using Tests as a reference

At the source code there is several unit tests that show how to use the Groovy builder. Check them out here.

Configuration

This plugin does not require specific configuration parameters by default.

If you plan to use the REST API then you should provide your Tropo username and password as most of the REST API methods are secured by default. In this case you need to add the following lines to your Config.groovy file providing your Tropo username and password:

Interacting with Tropo REST API

Tropo REST API allows you to interact with Tropo platform through a REST based service. This API can be used to directly invoke your applications (for example you could provide a phone image link in your webapp GUI that will invoke your application and trigger the Controller that we saw in the 5 minutes tutorial). Another usage for this API is to administer your account. You can use this API to create new applications, create and delete phone numbers, create and delete IM accounts, send signals to your application (like hanging up), etc. In summary, it is an admin and provisioning API.

Although you could send the REST requests yourself, this plugin provides a handy Grails service named TropoService that is injected in your applications and that you may use to execute all the different Tropo REST API calls.

Here is an example on how simple would be to launch your Tropo application using the TropoService:

As you can see in the code above, some of the TropoService calls will require a token. Each Tropo application has a unique token for handling voice calls and a different token for handling messaging. You can find your application's tokens at your application page in Tropo.com

IMPORTANT: Transcription issues

The interaction with Tropo is based on the interchange of JSON based documents. There is a known bug where Tropo sends transcription POST requests with a Content-Type header set to 'application/x-www-form-urlencoded' which basically will make the JSON coverter to fail with a message pretty similar to "org.codehaus.groovy.grails.web.json.JSONException: Missing value. at character 0 of "

If you face this issue the workaround is to disable Grails' automcatic content handling and parse the POST body yourself with the JSON converter. This is actually pretty easy. Here is an example:

Examples using the Tropo Builder

As you could see in the 5 minutes tutorial above, this plugin provides a groovy builder that makes really easy to interact with the Tropo platform. The following examples showcase some of the actions that you could do in your Grails applications.

Displaying the outcome of your application actions

In the example above we've seen how we can redirect to a different controller to handle the user's input like for example when entering a number or saying something. How can we get the user input from our controllers?

It is really easy. Tropo will send a POST request to our controller containing the result of the action that we have executed. That includes any input from the user:

Author

Please report any issues to the guys at Voxeo support. You can also use the Grails User mailing list and/or write up an issue in JIRA at http://jira.codehaus.org/browse/GRAILSPLUGINS under the Tropo-Webapi-Grails component.