How to Call the Twilio API from Java Programs on the Commandline

November 30, 2018
Written by

Twilio logo and Java program

If you you need to do a quick Twilio test, or compile and run programs on a remote computer without any GUI, or run test programs on your own computer and you don’t want to use a full blown IDE development environment, this is the article for you.

Check Java Installation

Confirm that you have a Java runtime environment (JRE) on your computer for running Java class files:

$ java -version
java version "1.8.0_131"<br/>Java(TM) SE Runtime Environment (build 1.8.0_131-b11)<br/>Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode)
Check that you have the Java compiler on your computer:
$ javac
Usage: javac <options> <source files>
…

If you don’t have both, please go to Oracle’s Java SE page and download the Java JDK.

The Java Standard Edition (Java SE) is what you need for developing and running Java programs from command line. Java SE has a Java Development Kit (JDK) which contains a Java Virtual Machine (JVM), the runtime environment (JRE) for running Java programs, and the compiler (javac).

Create and Run a Hello World Program

Create a working directory, for example: /projects/jtwilio. Before trying a Twilio request program, create and run the Hello World program, hello.java. This will confirm your environment is setup and working.

public class hello {
    public static void main(String[] args) {
        System.out.println("Hello world.");
    }
}

Compile the file into bytecode using the javac command.

$ javac hello.java 
$ ls -l
total 17968
-rw-r--r--  1 dthurston  410487729      416 Oct 26 15:13 hello.class
-rw-r--r--  1 dthurston  410487729      118 Oct 26 15:13 hello.java
...

Run the program using the JVM. The JVM is an interpreter that reads and runs the hello.class file.

$ java hello
Hello world.

You now have a tested, working Java environment to compile and run Java programs. Next, is to integrate the Twilio Java helper library into your compilations and run the programs using the helper library.

Create and Run a Twilio API Request Java Program

Download the Twilio helper library JAR file into your working directory. JAR stands for Java ARchive file. Essentially a JAR file is an archive zip file. Go to the repository directory and download the recent helper JAR file. At the time of writing the most recent JAR file is 7.29.0.

Create a program to list your Twilio account phone numbers: listAccNums.java.

import com.twilio.Twilio;
import com.twilio.base.ResourceSet;
import com.twilio.rest.api.v2010.account.IncomingPhoneNumber;
public class listAccNums {
    public static void main(String[] args) {
        Twilio.init("ACXXXXXX","YYYYYYYY");
        System.out.println("+ List account numbers:");
        ResourceSet<IncomingPhoneNumber> accnumbers = IncomingPhoneNumber.reader().read();
        for (IncomingPhoneNumber number : accnumbers) {
            System.out.println(
                    "++ " + number.getPhoneNumber()
                    + " " + number.getDateCreated()
                    + " " + number.getFriendlyName()
            );
        }
    }
}

You can view the contents of a JAR file using the jar command. You could rename the JAR file to have the extension, “.zip” and unzip the file to see the contents. But the jar command is much easier.

$ jar -tf twilio-7.29.0-jar-with-dependencies.jar
META-INF/
META-INF/MANIFEST.MF
META-INF/maven/
…
org/apache/http/client/methods/RequestBuilder.class
org/apache/http/client/methods/HttpGet.class
…
com/twilio/rest/api/v2010/account/IncomingPhoneNumberReader.class
… 
com/twilio/rest/api/v2010/account/IncomingPhoneNumber.class
… 
com/twilio/rest/taskrouter/
…
com/twilio/rest/trunking/
… 
com/twilio/rest/accounts/
… 
com/twilio/rest/voice/
… 
com/twilio/rest/wireless/
…

Note, in the above listing, is the file: IncomingPhoneNumberReader.class, which is imported into the sample program: listAccNums.java.

Compile the program. List the class file program. Run the program.

$ javac -cp twilio-7.29.0-jar-with-dependencies.jar listAccNums.java
$ ls -l
-rw-r--r--  1 dthurston  410487729      416 Oct 26 15:13 hello.class
-rw-r--r--  1 dthurston  410487729      118 Oct 26 15:13 hello.java
-rw-r--r--  1 dthurston  410487729     1707 Oct 26 15:22 listAccNums.class
-rw-r--r--  1 dthurston  410487729     1072 Oct 26 15:22 listAccNums.java
-rw-r--r--@ 1 dthurston  410487729  9185399 Oct 25 18:36 twilio-7.29.0-jar-with-dependencies.jar
$ java -cp .:twilio-7.29.0-jar-with-dependencies.jar listAccNums
+ List account numbers:
++ +16505551111 2017-11-20T19:04:46.000Z (650) 555-1111
++ +16505552222 2018-10-25T19:32:20.000Z (650) 555-2222
…

The compile command includes the Twilio helper library JAR file. The run command includes the Twilio helper JAR file, and the current directory: “.” which his where the class file listAccNums.class is located. “-cp” is the short form for “-classpath”.

Optionally, create a scripts for compiling and running your Twilio Java programs. Put script in your PATH for ease of execution. Following are my UNIX script examples: jc for compiling, jr for running.

$ cat /usr/local/bin/jc
javac -cp twilio-7.29.0-jar-with-dependencies.jar $1.java
$ chmod u+x usr/local/bin/jc

$ cat /usr/local/bin/jr
java -cp .:twilio-7.29.0-jar-with-dependencies.jar $1
$ chmod u+x usr/local/bin/jr

Test the scripts by re-compiling the account phone number list program and re-running it.

$ jc listAccNums
$ jr listAccNums
+ List account numbers:
+ List account numbers:
++ +16505551111 2017-11-20T19:04:46.000Z (650) 555-1111
++ +16505552222 2018-10-25T19:32:20.000Z (650) 555-2222
…

With jc and jr, you have an easy way to compile and run Twilio Java programs.

If you are using an IDE, and you need a quick method to add the Twilio Java library, without using Gradle or Maven, you can download the library JAR file and include it in your IDE’s project. The following screen print shows the JAR file included in my NetBeans project. The same approach will work with Eclipse.

Java application

Summary

There you have it, a quick methods of running Java programs that use the Twilio Java helper library to make Twilio REST API requests, using a minimum amount of setup. This is handy for quick testing and managing programs on remote computers where command line is the only option.

To help you get started writing Twilio Java programs, take a look at these set of programs I recently created based on the Twilio documentation.