Make Outbound Phone Calls with Java

In this guide, we'll show you how to use Programmable Voice to make outbound phone calls from your Java applications. It's pretty easy - all you'll need is the Twilio library for Java, a voice-capable Twilio phone number, your Twilio account credentials, and five minutes to have a boatload of fun at your keyboard. Let's get started!

Purchase a voice-enabled Twilio phone number

In the Twilio console, search for and purchase an available phone number capable of making outbound calls. You'll use this phone number as the "From" phone number when you initiate an outbound call.

Search for voice capable numbers

Retrieve your Twilio account credentials

First, you'll need to get your Twilio account credentials. They consist of your AccountSid and your Auth Token. They can be found on the home page of the console.

Retrieve Your Twilio Credentials

Make an outbound call

Now we're ready to make an outbound call using the Twilio Java library.

Loading Code Samples...
Language
SDK Version:
  • 6.x
  • 7.x
Format:
  • JSON
  • XML
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

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) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "+14155551212"));
    params.add(new BasicNameValuePair("From", "+15017250604"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Install the Java helper library from twilio.com/docs/java/install
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 {
  // 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) 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());
  }
}
{
	"sid": "CAa346467ca321c71dbd5e12f627deb854",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "+14155551212",
	"formatted_to": "(415) 555-1212",
	"from": "+14158675309",
	"formatted_from": "(415) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAa346467ca321c71dbd5e12f627deb854</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14155551212</To>
		<FormattedTo>(415) 555-1212</FormattedTo>
		<From>+14158675309</From>
		<FormattedFrom>(415) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
Make an outbound call

There are a few key parameters to drill into when making the outbound call.

  • "From" - the voice-enabled Twilio phone number you added to your account earlier
  • "To" - the person you'd like to call
  • "Url" - A URL that returns TwiML with instructions on what should happen when the other party picks up the phone

What is TwiML?

TwiML is the Twilio Markup Language, which is just to say that it's an XML document with special tags defined by Twilio to help you build your SMS and voice applications. TwiML is easier shown than explained:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Thanks for calling!</Say>
</Response>

Every TwiML document will have the root <Response> element and within that can contain one or more verbs. Verbs are actions you'd like Twilio to take, such as <Say> a greeting to a caller, or send an SMS <Message> in reply to an incoming message. For a full reference on everything you can do with TwiML, refer to our TwiML API Reference.

Loading Code Samples...
Language
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say voice="alice">Thanks for trying our documentation. Enjoy!</Say>
  <Play>https://demo.twilio.com/docs/classic.mp3</Play>
</Response>
This XML document uses the <Say> and the <Play> TwiML tags to read a message and play an MP3 file for the user.
The TwiML used to make the outbound call

This XML document uses the <Say> and the <Play> TwiML tags to read a message and play an MP3 file for the user.

Of course, the TwiML you use to make the outbound call doesn't need to be a static file like in this example. Server-side Java code that you control can dynamically render TwiML to use for the outbound call.

Where to next?

Great work! In a few lines of code, you've placed an outbound phone call from your Java code. If you're interested in learning more about building voice applications in Java, perhaps we could tempt you with a few tutorials? Tutorials walk through full sample applications that implement production Twilio use cases, like these:

Kevin Whinnery
Andrew Baker
Ricky Robinett
David Prothero
Jarod Reyes
Rob Spectre

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 browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
SDK Version:
  • 6.x
  • 7.x
Format:
  • JSON
  • XML
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

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) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("To", "+14155551212"));
    params.add(new BasicNameValuePair("From", "+15017250604"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Install the Java helper library from twilio.com/docs/java/install
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 {
  // 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) 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());
  }
}
{
	"sid": "CAa346467ca321c71dbd5e12f627deb854",
	"date_created": "Thu, 19 Aug 2010 00:12:15 +0000",
	"date_updated": "Thu, 19 Aug 2010 00:12:15 +0000",
	"parent_call_sid": null,
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"to": "+14155551212",
	"formatted_to": "(415) 555-1212",
	"from": "+14158675309",
	"formatted_from": "(415) 867-5309",
	"phone_number_sid": "PNd6b0e1e84f7b117332aed2fd2e5bbcab",
	"status": "queued",
	"start_time": null,
	"end_time": null,
	"duration": null,
	"price": null,
	"direction": "outbound-api",
	"answered_by": null,
	"api_version": "2010-04-01",
	"forwarded_from": null,
	"caller_name": null,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854.json",
	"subresource_uris": {
		"notifications": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Notifications.json",
		"recordings": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/Calls\/CAa346467ca321c71dbd5e12f627deb854\/Recordings.json"
	}
}
<TwilioResponse>
	<Call>
		<Sid>CAa346467ca321c71dbd5e12f627deb854</Sid>
		<DateCreated>Thu, 19 Aug 2010 00:25:48 +0000</DateCreated>
		<DateUpdated>Thu, 19 Aug 2010 00:25:48 +0000</DateUpdated>
		<ParentCallSid/>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<To>+14155551212</To>
		<FormattedTo>(415) 555-1212</FormattedTo>
		<From>+14158675309</From>
		<FormattedFrom>(415) 867-5309</FormattedFrom>
		<PhoneNumberSid></PhoneNumberSid>
		<Status>queued</Status>
		<StartTime/>
		<EndTime/>
		<Duration/>
		<Price/>
		<Direction>outbound-api</Direction>
		<AnsweredBy/>
		<ApiVersion>2010-04-01</ApiVersion>
		<ForwardedFrom/>
		<CallerName/>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854</Uri>
		<SubresourceUris>
			<Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Notifications</Notifications>
			<Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAa346467ca321c71dbd5e12f627deb854/Recordings</Recordings>
		</SubresourceUris>
	</Call>
</TwilioResponse>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say voice="alice">Thanks for trying our documentation. Enjoy!</Say>
  <Play>https://demo.twilio.com/docs/classic.mp3</Play>
</Response>