Twilio Client for Android Quickstart Tutorial

The Eclipse project

Please open the "HelloMonkey" Eclipse project in Quickstart folder (File -> Import -> General -> Existing Projects into Workspace).

The HelloMonkey app is very simple, presenting "Dial" and "Hangup" buttons, and a text field for who the app should call. The user interface elements have already been wired up to the HelloMonkeyActivity class.

In this step, you'll fill in the code to give the app its behavior, learning how to use the Twilio Client Android SDK in the process.

Creating a Device

The primary class for connecting to Twilio services from your app is Device. This class represents a soft "device" that knows how to speak to Twilio services, coordinates service authorization with Twilio, listens for incoming connections, and establishes outgoing connections. An instance of this class is created using a "capability token", described in the next section.

You'll use a Device to initiate outgoing calls and listen for incoming calls. Let's create an instance and wire it up!

Add a member variable of type Device to MonkeyPhone.java like so:

import com.twilio.client.Device;
import com.twilio.client.Twilio;

public class MonkeyPhone implements Twilio.InitListener
{
    private Device device; 
}

To initialize a device, you'll change the URL to point to your server's /token URL and pass the resulting string to - HttpHelper.httpGet() method (you may want to make necessary changes to run this code in separate thread).

Note: Make sure you swap in your back-end server's /token URL for the sample URL in MonkeyPhone's onInitialized method.

MonkeyPhone.java
import com.twilio.client.Device;
import com.twilio.client.Twilio;

public class MonkeyPhone implements Twilio.InitListener
{
    private Device device;

    public MonkeyPhone(Context context)
    {
        Twilio.initialize(context, this /* Twilio.InitListener */);
    }

    @Override /* Twilio.InitListener method */
    public void onInitialized()
    {
        Log.d(TAG, "Twilio SDK is ready");

        new RetrieveCapabilityToken().execute("http://companyfoo.com/token");
    }

}

Making an HTTP request to the /token endpoint returns a capability token, a string that, when given to a Device in your Android app, grants it capabilities such as making outgoing calls or allowing incoming calls.

Capability tokens are an important part of Twilio Client, so let's take a moment to explain them. You use capability tokens to sign communications from your Android app to Twilio. In a production application, these tokens are created by you on your server and allow you to specify what capabilities are going to be available to your app, such as whether it can receive incoming connections, make outgoing connections, etc.

For the security of your Twilio account, you should not embed a Capability Token or your Twilio Account's Auth Token in the app you submit to the Google Play Store.

You can read more about capability tokens and their best practices here.

Tokens always have an expiration, which means all tokens have a limited lifetime to protect you from abuse. The token generated here is valid for one hour unless otherwise specified. To specify a different period of time, pass in the number of seconds as the expires parameter to TwilioCapability.generate() -- for example, for a token that expires after 5 minutes, call TwilioCapability.generate(expires = 300). The maximum allowed lifetime for a token is 24 hours.

Now, back to coding! If you compile and run this code, you should see the following:

Hello Monkey Screenshot

Now, we've got an app that can create outgoing connections and receive incoming connections.

For the time being, we'll focus on making an outgoing connection. The connection will call a Twilio sample application that responds with a friendly greeting.

Dialing Out

Let's add a method to MonkeyPhone to initiate a connection. Add a member variable of type Connection to MonkeyPhone.java. To make a connection, we call the Device.connect() method. Just pass in null parameters and a null listener for the moment; we'll do more with these arguments later.

MonkeyPhone.java
public void connect()
{
    connection = device.connect(null /* parameters */, null /* ConnectionListener */);
    if (connection == null)
        Log.w(TAG, "Failed to create new connection");
}

Connections to Twilio, either incoming or outgoing, are represented by instances of the class Connection. In addition, status callbacks are provided to objects that implement the listener interface DeviceListener and ConnectionListener. Add the code below in HelloMonkeyActivity to call this new method when the Dial button is pressed:

HelloMonkeyActivity.java
@Override
public void onClick(View view)
{
    if (view.getId() == R.id.dialButton)
        phone.connect();
}

If you now compile the app and run it, you should be able to click the "Dial" button and hear the greeting. Awesome!

Wouldn't it be nice if you could also hang up on a connection if you don't want to hear the whole thing? Let's go do that now.


Next: Hanging up from your Android Device »