Get Started

The Twilio Java Helper Library

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

This library is open source, so if you find a feature missing or a bug, we encourage you to contribute back to the twilio-java project hosted on Github.

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.

You may also want to refer to the REST and TwiML examples in the open source repository and the twilio-java javadocs for more details about the classes and methods contained in the SDK.

Installation

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.5</version>
    </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.MessageFactory;
import com.twilio.sdk.resource.instance.Message;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

import java.util.ArrayList;
import java.util.List;

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 MessageList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Body", "Jenny please?! I love you <3"));
    params.add(new BasicNameValuePair("To", "+14159352345"));
    params.add(new BasicNameValuePair("From", "+14158141829"));

    MessageFactory messageFactory = client.getAccount().getMessageFactory();
    Message message = messageFactory.create(params);
    System.out.println(message.getSid());
  }
}

Using the Library

Try the Java quickstarts and refer to the examples in the open source project repo, as well as the javadocs for details about the methods and classes contained in the library.

Handling 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 MessageList
        List<NameValuePair> params = new ArrayList<NameValuePair>();
        params.add(new BasicNameValuePair("Body", "Jenny please?! I love you <3"));
        params.add(new BasicNameValuePair("To", "+14159352345"));
        params.add(new BasicNameValuePair("From", "+14158141829"));


        MessageFactory messageFactory = client.getAccount().getMessageFactory();
        Message message = messageFactory.create(params);
    } catch (TwilioRestException e) {
        System.out.println(e.getErrorMessage());
    }
}

Getting help

Still running into problems?