Get Started

Install the Twilio Java Helper Library

The twilio-java helper library lets you write Java code to make HTTP requests to the Twilio API.

The easiest way to install twilio-java is from Maven. You can add the following dependency to your existing project, specifying the latest version in the version tag:

pom.xml
    <dependency>
        <groupId>com.twilio.sdk</groupId>
        <artifactId>twilio-java-sdk</artifactId>
        <version>3.4.1</version>
        <scope>compile</scope>
    </dependency>

Or, you can clone the source code for twilio-java, and install the library from there.

git clone git@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, ex. sudo mvn install, if you get "Permission Denied" errors while trying to install the library.

Pre-built jars are also available here. Select the directory for the latest version and download one of these jar files:

  • twilio-java-sdk-3.x.x-with-dependencies.jar
  • twilio-java-sdk-3.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 twilio-java for the list of libraries.

Testing your installation

Try sending yourself an SMS message, like this:

Example.java
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.SmsFactory;
import com.twilio.sdk.resource.instance.Sms;
import com.twilio.sdk.resource.list.SmsList;
import java.util.HashMap;
import java.util.Map;

public class Example {

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "AC32a3c49700934481addd5ce1659f04d2";
  public static final String AUTH_TOKEN = "";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the SmsList
    Map<String, String> params = new HashMap<String, String>();
    params.put("Body", "Jenny please?! I love you <3");
    params.put("To", "+14159352345");
    params.put("From", "+14158141829");

    SmsFactory messageFactory = client.getAccount().getSmsFactory();
    Sms message = messageFactory.create(params);
    System.out.println(message.getSid());
  }
}

More Documentation

The Rest API Documentation has examples written in Java for every kind of action you could take with the Twilio API. You should start there if you know what you want to do with the Java library. If you'd like to learn more about how Twilio works, or for inspiration about what to build, try the Java quickstarts.

Exceptions

If the Twilio API returns a 400 or a 500 level HTTP response, the twilio-java library will throw a TwilioRestException. 400-level errors are normal during API operation ("Invalid number", "Cannot deliver SMS to that number", for example) and should be handled appropriately.

import com.twilio.sdk.TwilioRestException;

public static void main(String[] args) {
    try {
        TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

        // Build a filter for the SmsList
        Map<String, String> params = new HashMap<String, String>();
        params.put("Body", "Hello World");
        params.put("To", "+14159352345");
        params.put("From", "+14158141829");

        SmsFactory messageFactory = client.getAccount().getSmsFactory();
        Sms message = messageFactory.create(params);
    } catch (TwilioRestException e) {
        System.out.println(e.getErrorMessage());
    }
}

Getting help

Still running into problems?