twilio-java

The default branch name for this repository has been changed to main as of 07/27/2020.

Documentation

The documentation for the Twilio API can be found here.

The Java library documentation can be found here.

Versions

twilio-java uses a modified version of Semantic Versioning for all changes. See this document for details.

TLS 1.2 Requirements

New accounts and subaccounts are now required to use TLS 1.2 when accessing the REST API. "Upgrade Required" errors indicate that TLS 1.0/1.1 is being used.

Supported Java Versions

This library supports the following Java implementations:

OpenJDK 8
OpenJDK 11
OracleJDK 8
OracleJDK 11

For Java 7 support, use twilio-java major version 7.X.X.

Installation

twilio-java uses Maven. At present the jars are available from a public maven repository.

Use the following dependency in your project to grab via Maven:

       <dependency>
          <groupId>com.twilio.sdk</groupId>
          <artifactId>twilio</artifactId>
          <version>8.X.X</version>
          <scope>compile</scope>
       </dependency>

or Gradle:

implementation "com.twilio.sdk:twilio:8.X.X"

If you want to compile it yourself, here's how:

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

If you want to build your own .jar, execute the following from within the cloned directory:

$ mvn package

If you run into trouble with local tests, use:

$ mvn package -Dmaven.test.skip=true

Quickstart

Initialize the Client

// Find your Account SID and Auth Token at twilio.com/console
// DANGER! This is insecure. See http://twil.io/secure
String accountSid = "ACXXXXXX";
String authToken = "XXXXXXXX";

Twilio.init(accountSid, authToken);

Specify Region and/or Edge

To take advantage of Twilio's Global Infrastructure, specify the target Region and/or Edge for the client:

Twilio.init(accountSid, authToken);
Twilio.setRegion("au1");
Twilio.setEdge("sydney");

This will result in the hostname transforming from api.twilio.com to api.sydney.au1.twilio.com.

Enable Debug Logging

This library uses SLF4J for logging. Consult the SFL4J documentation for information about logging configuration:

http://slf4j.org/docs.html

For example, if you are using log4j, make sure you have slf4j-log4j12-1.X.XX.jar, log4j-1.X.XX.jar and slf4j-api-1.X.XX.jar in your classpath and a log4j.properties file in the root of your project.

Environment Variables

twilio-java supports the credentials, region, and edge values stored in the following environment variables:

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_REGION
TWILIO_EDGE

If using these variables, the above client initialization can be skipped.

Send an SMS

Message message = Message.creator(
    new PhoneNumber("+15558881234"),  // To number
    new PhoneNumber("+15559994321"),  // From number
    "Hello world!"                    // SMS body
).create();

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

Make a Call

Call call = Call.creator(
    new PhoneNumber("+15558881234"),  // To number
    new PhoneNumber("+15559994321"),  // From number

    // Read TwiML at this URL when a call connects (hold music)
    new URI("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
).create();

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

Handling Exceptions

import com.twilio.exception.ApiException;

try {
    Message message = Message.creator(
        new PhoneNumber("+15558881234"),  // To number
        new PhoneNumber("+15559994321"),  // From number
        "Hello world!"                    // SMS body
    ).create();

    System.out.println(message.getSid());
} catch (final ApiException e) {
    System.err.println(e);
}

For more descriptive exception types, please see the Twilio documentation.

Using a Different Client

TwilioRestClient client = new TwilioRestClient.Builder(accountSid, authToken).build();

Message message = Message.creator(
    new PhoneNumber("+15558881234"),  // To number
    new PhoneNumber("+15559994321"),  // From number
    "Hello world!"                    // SMS body
).create(client);  // Pass the client here

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

Using a Client With PKCV Authentication

Additional documentation here: https://twilio.com/docs/iam/pkcv/quickstart

ValidationClient httpClient = new ValidationClient(ACCOUNT_SID, key.getSid(), signingKey.getSid(), pair.getPrivate());
TwilioRestClient client = new TwilioRestClient.Builder(signingKey.getSid(), signingKey.getSecret())
    .accountSid(ACCOUNT_SID)
    .httpClient(httpClient)
    .build();

Generating TwiML

To control phone calls, your application needs to output TwiML.

TwiML in twilio-java now use the builder pattern!

TwiML twiml = new VoiceResponse.Builder()
    .say(new Say.Builder("Hello World!").build())
    .play(new Play.Builder("https://api.twilio.com/cowbell.mp3").loop(5).build())
    .build();

That will output XML that looks like this:

<Response>
    <Say>Hello World!</Say>
    <Play loop="5">https://api.twilio.com/cowbell.mp3</Play>
</Response>

Using a Custom HTTP Client

To use a custom HTTP client with this helper library, please see the Twilio documentation.

Docker Image

The Dockerfile present in this repository and its respective twilio/twilio-java Docker image are currently used by Twilio for testing purposes only.

Getting Help

If you need help installing or using the library, please check the Twilio Support Help Center first, and file a support ticket if you don't find an answer to your question.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

rpax/twilio-java