The Twilio Java Helper Library

The Twilio Java SDK helps you interact with the Twilio API from your Java application. The most recent version of the Twilio Java SDK can be found on Maven Repository. For the list of supported Java runtime versions, see the library reference documentation. If you are interested in migrating to the newer 9.x version of the Twilio Java SDK from the 8.x version, check out this guide.

Using with a build automation tool

The recommended method for installing the SDK is with a build automation tool, like Maven or Gradle. You can add the Twilio dependency to your existing project, specifying the latest version.

Maven

In Maven, place the following within your <dependencies> tag in your pom.xml file:

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio</artifactId>
  <version>9.2.2</version>
</dependency>

Gradle

In Gradle, paste the next line inside the dependencies block of your build.gradle file:

implementation group: "com.twilio.sdk", name: "twilio", version: "9.2.2"

Regardless of the package manager you are using, remember to specify the latest version of the Twilio Java SDK.

Install the SDK locally

You can also clone the source code for the SDK, and install the library from there.

git clone https://github.com/twilio/twilio-java
cd twilio-java
mvn install       # Requires maven, download from http://maven.apache.org/download.html

You may need to run the above command with sudo (e.g. sudo mvn install) if you get "Permission Denied" errors while trying to install the library.

If you are using Gradle in your project, and you want to install the SDK locally as we just described, you may need to add the next line inside the repositories block of your build.gradle file:

mavenLocal()

This line will instruct Gradle to look for packages on the local Maven repository, where we installed previously the Twilio Java SDK.

Using without a build automation tool

While we recommend using a package manager to track the dependencies in your application, it is possible to download and use the Java SDK manually by downloading a pre-built jar file. Select the directory for the latest version and download one of these jar files:

twilio-9.x.x-with-dependencies.jar
twilio-9.x.x.jar -- use this if you have issues with conflicting jars in your project. You'll need to include versions of the dependencies yourself. See the pom.xml file in the source code for the list of libraries.

Testing your Installation

Try sending yourself an SMS message, like this:

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

public class Example {
  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Message message = Message.creator(new PhoneNumber("+15558675309"),
        new PhoneNumber("+15017250604"), 
        "This is the ship that made the Kessel Run in fourteen parsecs?").create();

    System.out.println(message.getSid());
  }
}

It's okay to hard-code your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out How to Set Environment Variables for more information.

Using This Library

Authenticate Client

import com.twilio.Twilio;
import com.twilio.exception.AuthenticationException;

public class Example { 

  private static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  private static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws AuthenticationException { 
     Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
  } 
}

Create A New Record

import java.net.URI;
import java.net.URISyntaxException;

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;
import com.twilio.type.PhoneNumber;

public class Example {
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws URISyntaxException {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Call call = Call.creator(new PhoneNumber("+14155551212"), new PhoneNumber("+15017250604"),
        new URI("http://demo.twilio.com/docs/voice.xml")).create();

    System.out.println(call.getSid());
  }
}

Get Existing Record

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;

public class Example {
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Call call = Call.fetcher("CA42ed11f93dc08b952027ffbc406d0868").fetch();

    System.out.println(call.getTo());
  }
}

Iterate Through Records

import com.twilio.Twilio;
import com.twilio.base.ResourceSet;
import com.twilio.rest.api.v2010.account.Call;

public class Example {
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    ResourceSet<Call> calls = Call.reader().read();

    for (Call call : calls) {
      System.out.println(call.getDirection());
    }
  }
}

The library automatically handles paging for you. With the read method, you can specify the number of records you want to receive (limit) and the maximum size you want each page fetch to be (pageSize). The library will then handle the task for you, fetching new pages under the hood as you iterate over the records.

For more information, view the auto-generated library docs.

Accessing the 8.x Version of the SDK

The most recent version of the Java SDK is not API compatible with the previous 8.x version of the Java SDK you may have used in previous Twilio applications. The older version will continue to work, and you will continue to find sample code for this version throughout our documentation. Should you need to install this version with Maven, you can do so with the following dependency in your pom.xml file:

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio-java-sdk</artifactId>
  <version>8.36.0</version>
</dependency>

Getting Help

We'd love to hear your feedback on the Java SDK, and help you past any issues you may encounter. Feel free to drop us a line, and we'll make sure to get you sorted!

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Need some help?

Thank you for your feedback!

Thanks for your feedback!