Building a Twilio Client Web App – Part 1

| 166 Comments

I was very excited when Twilio announced Twilio Client this week. I immediately knew I wanted to build something with it (and not just because I want to win cool stuff!). This blog post is the first part of a series where I’ll show you how to build your own Twilio Client web app. By the end of it I hope you’ll be as excited about the technology as I am.

What Is Twilio Client?

You’ve seen the flood of tweets, the apps people have been putting together and the many blog post, but you may still be asking “What is Twilio Client?”. Technically speaking (and taken directly from Twilio’s website) it’s “audio pipes for voice communication in web and mobile apps”. Practically speaking , I’d call it a drop-dead-simple SDK for adding voice communication to your apps. The web version uses JavaScript and Flash (+ your server side language of choice), the mobile versions (iOS, Anroid and Windows Mobile) use their native languages. Still confused? Continue reading and things will start to become more clear.

What You Need

Before we get started with the tutorial we need to cover a few general technology needs.

  1. A Twilio Client supported browser. You can test your browser at http://clientsupport.twilio.com. If you’re using OSX Lion don’t get freaked out by the work-around they have you do. It’s pretty straight-forward.
  2. A web-server to run the code on. This server should have PHP >= 5.2.1 and the PHP JSON extension.

You’ll also need to get a couple pieces of Twilio specific data.

  1. Access your Account Dashboard and make note of your Account SID, App SID and Auth Token. Don’t have an account? Sign up for a free trial. I promise you’ll be thanking me later.
  2. Grab the twilio-php helper library. You can do so using PEAR with these instructions or you can just grab the source. If you use PEAR, make sure your PEAR is up-to-date as there have been reports of some installation issues with older version of PEAR.

Code Time! Generating Capability Token

The first thing we need to do is generate a Twilio capability token. A capability token is a secure way to allow the your application to access Twilio. With Twilio Client, tokens allow you to avoid exposing your Account Auth Token on the client-side.

We’ll use the following code to generate our token, place it in a php file named as you choose:

<?php

require_once('Services/Twilio/Capability.php');

// Your API credentials from Account Dashboard here
$accountSid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$authToken = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy';
$appSid = 'APzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz';

$capability = new Services_Twilio_Capability($accountSid, $authToken);
// give this app permissions
$capability->allowClientOutgoing($appSid);
// generate token that lasts for 5 minutes
$token = $capability->generateToken(300);

?>

Let’s dissect this code a bit. First, we do some basic setup by requiring the Twilio Capability file and setting some convenience variables with our Account SID, Auth Token and App SID.  We then get to the heart of the code. We initiate a new Services_Twilio_Capability object and assign it to the variable capability. We then give the permission of allowClientOutgoing for our app idea. This permission will allow this app to make outgoing calls (we’ll get to other permissions in Part 2 of this series). Finally, we generate the token and save it for later use. Note that we’re passing generateToken the value 300, this is the expiration length for this token in seconds. It defaults to 1 hour, but it’s recommended to configure this for as short as possible and then generate a new token as needed.

Setting Up Our Page

Now that we have a token, we can setup our client-side code for Twilio Client. We’ll be working in the same php file we generated the token in. First, we’ll add the Twilio JavaScript library and jQuery library to the head of our page.

<!DOCTYPE html>
<html>
<head>
<title>Twilio Client Test</title>
<script type="text/javascript"
src="http://static.twilio.com/libs/twiliojs/1.0/twilio.min.js"></script>
<script type="text/javascript"
src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
</script>
</head>

Next we’ll setup our app as a Twilio device using our Capability Token and add some callback functions to handle Twilio Client state changes by adding the following JavaScript to the head of our page.

<script type="text/javascript">
Twilio.Device.setup("<?php echo $token; ?>");
Twilio.Device.ready(function (device) {
// handle device ready
});
Twilio.Device.error(function (error) {
// handle device error
});
Twilio.Device.connect(function (conn) {
// handle device connect
});
Twilio.Device.disconnect(function (conn) {
// handle device disconnect
});
function call() {
// make call
Twilio.Device.connect();
}
function hangup() {
Twilio.Device.disconnectAll();
}
</script>

You can setup the ready, error, connect and disconnect functions as you desire. Whether it’s logging to the console or updating text on the page itself. It’s definitely recommended to have them do something to help you debug in case you encounter any errors or the app isn’t behaving how you’d expect.

Making a Call!!!

We’ve made it to the promise land! You’re about ready to make a call from your browser! Let’s add two links to our page that allow users to make a call and hangup.

<body>
<h1>Twilio Client Test</h1>
<a href="#" onclick="call();return false;">Call</a>
|
<a href="#" onclick="hangup();return false;">Hangup</a>
</body>
</html>

You should now be able to run your page, click call and you’ll hear the Twilio welcome message. Hit hangup and the call will end. Incredible! In a short amount of time we were able to turn your web browser in an audio communication app powered by the Twilio Client.

Part 2 of this tutorial is up now! Check it out!