Skip to contentSkip to navigationSkip to topbar
On this page

Make Outbound Phone Calls with Java


(warning)

Warning

Twilio is launching a new Console. Some screenshots on this page may show the Legacy Console and therefore may no longer be accurate. We are working to update all screenshots to reflect the new Console experience. Learn more about the new Console(link takes you to an external page).

In this guide, we'll show you how to use Programmable Voice(link takes you to an external page) to make outbound phone calls from your Java applications. You'll need the Twilio library for Java(link takes you to an external page), a voice-capable Twilio phone number, your Twilio account credentials, and five minutes. Let's get started!

(warning)

Warning

If you are sending SMS messages to the U.S. or Canada, before proceeding further please be aware of updated restrictions on the use of Toll-Free numbers for messaging, including TF numbers obtained by purchasing them. These restrictions do not apply to Voice or other uses outside of SMS messaging. Please click here(link takes you to an external page) for details.

In the Twilio console(link takes you to an external page), 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

retrieve-your-twilio-account-credentials page anchor

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(link takes you to an external page).

Retrieve Your Twilio Credentials.

Make an outbound call

make-an-outbound-call page anchor

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

Make an outbound callLink to code sample: Make an outbound call
1
// Install the Java helper library from twilio.com/docs/java/install
2
3
import com.twilio.type.Twiml;
4
import com.twilio.Twilio;
5
import com.twilio.rest.api.v2010.account.Call;
6
7
public class Example {
8
// Find your Account SID and Auth Token at twilio.com/console
9
// and set the environment variables. See http://twil.io/secure
10
public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
11
public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
12
13
public static void main(String[] args) {
14
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
15
Call call = Call.creator(new com.twilio.type.PhoneNumber("+14155551212"),
16
new com.twilio.type.PhoneNumber("+15017122661"),
17
new com.twilio.type.Twiml("<Response><Say>Ahoy, World!</Say></Response>"))
18
.create();
19
20
System.out.println(call.getSid());
21
}
22
}

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"annotation": null,
4
"answered_by": null,
5
"api_version": "2010-04-01",
6
"caller_name": null,
7
"date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
8
"date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
9
"direction": "inbound",
10
"duration": "15",
11
"end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
12
"forwarded_from": "+141586753093",
13
"from": "+15017122661",
14
"from_formatted": "(415) 867-5308",
15
"group_sid": null,
16
"parent_call_sid": null,
17
"phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"price": "-0.03000",
19
"price_unit": "USD",
20
"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21
"start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
22
"status": "completed",
23
"subresource_uris": {
24
"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
25
"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
26
"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
27
"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
28
"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
29
"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
30
"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
31
"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
32
"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
33
},
34
"to": "+14155551212",
35
"to_formatted": "(415) 867-5309",
36
"trunk_sid": null,
37
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
38
"queue_time": "1000"
39
}

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
  • TwiML - Instructions in the form TwiML that explains what should happen when the other party picks up the phone
  • Url - Optionally, instead of passing the TwiML parameter, you can provide a URL that returns TwiML Voice instructions.

TwiML is the Twilio Markup Language, which is just to say that it's an XML(link takes you to an external page) document with special tags defined by Twilio to help you build your SMS and voice applications. TwiML is easier shown than explained. Here's some TwiML you might use to respond to an incoming phone call:

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

And here's some TwiML you might use to respond to an incoming SMS message:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Message>We got your message, thank you!</Message>
4
</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.

1
// Install the Java helper library from twilio.com/docs/java/install
2
3
import java.net.URI;
4
import com.twilio.Twilio;
5
import com.twilio.rest.api.v2010.account.Call;
6
7
public class Example {
8
// Find your Account SID and Auth Token at twilio.com/console
9
// and set the environment variables. See http://twil.io/secure
10
public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
11
public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
12
13
public static void main(String[] args) {
14
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
15
Call call = Call.creator(new com.twilio.type.PhoneNumber("+14155551212"),
16
new com.twilio.type.PhoneNumber("+14155551212"),
17
URI.create("http://demo.twilio.com/docs/classic.mp3"))
18
.create();
19
20
System.out.println(call.getSid());
21
}
22
}

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"annotation": null,
4
"answered_by": null,
5
"api_version": "2010-04-01",
6
"caller_name": null,
7
"date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
8
"date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
9
"direction": "inbound",
10
"duration": "15",
11
"end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
12
"forwarded_from": "+141586753093",
13
"from": "+14155551212",
14
"from_formatted": "(415) 867-5308",
15
"group_sid": null,
16
"parent_call_sid": null,
17
"phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"price": "-0.03000",
19
"price_unit": "USD",
20
"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21
"start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
22
"status": "completed",
23
"subresource_uris": {
24
"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
25
"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
26
"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
27
"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
28
"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
29
"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
30
"transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
31
"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
32
"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
33
},
34
"to": "+14155551212",
35
"to_formatted": "(415) 867-5309",
36
"trunk_sid": null,
37
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
38
"queue_time": "1000"
39
}

The TwiML used to make the outbound call

the-twiml-used-to-make-the-outbound-call page anchor

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

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Say voice="Polly.Amy">Thanks for trying our documentation. Enjoy!</Say>
4
<Play>https://demo.twilio.com/docs/classic.mp3</Play>
5
</Response>

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.


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:

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.