Calling all Java developers – Making voice calls and sending SMS messages with Java

Java-logo

Did you know that Twilio offers helper libraries in a variety of programming languages to simplify the process of connecting your web application to Twilio? Java developers can use the Twilio Java Library to simplify making calls to the Twilio REST API, as well as generation of TwiML responses. We recently updated our HowTo’s and example code to include several Java examples, and over the next few days I’ll be blogging about some of the ways to connect your Java code to Twilio.

Downloading and Building the Twilio Java library

You can download the latest build of the Twilio Java library from its Github page. You will need to build the source files to create twiliorest.jar; take a look at the README file for instructions on how to do this using Apache Ant, or via shell script. You should then add twiliorest.jar on the classpath of your application, along with it’s dependency commons-codec-1.3.jar, which is included in the lib folder of the download.

Making calls from Java

Let’s take a look at a basic example of making calls using Java. I’ve borrowed from the TwilioRestExample.java file included with the library to show how you can use the Twilio REST API to place a call.

Here’s the code listing of our example java class:

Customizing, compiling and running

You’ll notice that you need to fill in a few values in the source code, including your AccountSid and AuthToken. You can find both of these on your Account Dashboard page. You will also need to input the CallerID the phone will show when it rings, which needs to be valid outgoing caller id in your account. Finally, input the number you’d like to call. For this example – enter your own phone number.

A nice enhancement to this program would be to allow these arguments to be passed in on the command line, but for clarity’s sake we’re hardcoding them here.

Next we need to compile the class, passing in the helper library on the classpath:

Now that our class is compiled, we’re ready to run the code! Make sure to pass in all the necessary classpath values.

Shortly after you run the program, your phone should be ringing!

Duke3D

Breaking it down

Let’s step through some of our program to understand what’s going on. It may be helpful to review the Twilio REST API Request format and Making Calls documentation before we get going.

The majority of first portion of the class is devoted to defining the parameters for the REST call. You can see the API version is defined as static; AccountSid and AuthToken are also possible candidates for being constants if your application will only be using a single Twilio account. These 3 parameters are common to all REST API calls.

Next, you will see the required parameters for making a call are defined, including the CallerID and number ToCall. Finally, the Url Twilio will call back to when the phone is answered is specified using Twimlets. Twilio requires the callback Url to be in TwiML, or Twilio Markup XML. Twimlets provide hosted access to TwiML responses. Twimlets cover a variety of use cases, but its likely as you develop your own custom application you will want to host TwiML response pages on your own server. Here is the contents of our callback Url, containing the TwiML Twilio will execute when the caller picks up the phone:

The next portion of code handles calling the REST API. First, we instantiate a TwilioRestClient object, and pass into it all of our credentials. Next, we load the required parameters into a Map object. This Map holds all the parameters we’re sending into the REST call. At this point we are ready to call the API. Per the documentation, to make a call we need to make a HTTP POST to the Calls resource, and pass in our required parameters. It’s worth noting that the structure of the API call we use here will be similar for other REST calls, whether you’re sending an SMS or checking call logs. Certain settings may vary, such as the resource path, HTTP method, or params value, but the overall pattern remains the same.

How Twilio interacts with your Java application

After the code has run, you’ve application will have made a request to Twilio to place a new call. Twilio will receive this request, briefly queue the call, and then ring the number. The number rings, showing the specified CallerID. When it’s answered, Twilio calls out to the Url passed in as a parameter to the REST call. The Url contains TwiML instructions on how to handle the call logic.

Twilio retrieves the contents of the Url, and processes the TwiML <Response> from top to bottom. First, Twilio encounters the <Say> Verb, which instructs Twilio to perform text to speech and talk to the caller. Next, the <Play> Verb tells Twilio to play the specified audio file to the caller, in this case some groovy music. After all TwiML tags have been processed, Twilio ends the call.

If something went wrong with your program, you should see the details output to the console. Check the debugging guide for more help.

What’s next

Congratulations on running your first Twilio Java program! As you develop your application, you might find our Quick Start guides, HowTos and example code and documentation useful. Stay tuned for more blog posts about integrating Twilio and Java.

You can contact Brian Levine, the author of this post, with any questions or comments.