Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Record Phone Calls in 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 record phone calls with your Java web application.

You will learn how to record inbound and outbound calls. In both examples we'll use Twilio's Java SDK(link takes you to an external page).


Set up your web application

set-up-your-web-application page anchor
Incoming Voice.

Twilio makes answering a phone call as easy as responding to an HTTP request. When a phone number you have bought through Twilio receives an incoming call, Twilio will send an HTTP request to your web application asking for instructions on how to handle the call. Your server will respond with an XML document containing TwiML that instructs Twilio on what to do with the call. Those instructions can direct Twilio to read out a message, play an MP3 file, make a recording and much more.

To start answering phone calls, you must:

  • Buy and configure a Twilio-powered phone number(link takes you to an external page) capable of making and receiving phone calls, and point it at your web application
  • Write a web application to tell Twilio how to handle the incoming call using TwiML
  • Make your web application accessible on the Internet so Twilio can make an HTTP request when you receive a call
(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.


Buy and configure a phone number

buy-and-configure-a-phone-number page anchor

In the Twilio Console, you can search for and buy phone numbers in countries around the world. Numbers that have the Voice capability can make and receive voice phone calls from just about anywhere on the planet.

Search for voice capable numbers.

Once you purchase a number, you'll need to configure that number to send a request to your web application. This callback mechanism is called a webhook(link takes you to an external page). This can be done in the number's configuration page.

configure an incoming phone number URL.

Webhooks are user-defined HTTP(link takes you to an external page) callbacks. They are usually triggered by some event, such as receiving an SMS message or an incoming phone call. When that event occurs, Twilio makes an HTTP request (usually a POST or a GET(link takes you to an external page)) to the URL configured for the webhook.

To handle a webhook, you only need to build a small web application that can accept the HTTP requests. Almost all server-side programming languages offer some framework for you to do this. Examples across languages include ASP.NET MVC(link takes you to an external page) for C#, Servlets(link takes you to an external page) and Spark(link takes you to an external page) for Java, Express(link takes you to an external page) for Node.js, Django(link takes you to an external page) and Flask(link takes you to an external page) for Python, and Rails(link takes you to an external page) and Sinatra(link takes you to an external page) for Ruby. PHP(link takes you to an external page) has its own web app framework built in, although frameworks like Laravel(link takes you to an external page), Symfony(link takes you to an external page) and Yii(link takes you to an external page) are also popular.

Whichever framework and language you choose, webhooks function the same for every Twilio application. They will make an HTTP request to a URI that you provide to Twilio. Your application performs whatever logic you feel necessary - read/write from a database, integrate with another API or perform some computation - then replies to Twilio with a TwiML response with the instructions you want Twilio to perform.

What is TwiML?

what-is-twiml page anchor

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:


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

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


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


Record an inbound phone call

record-an-inbound-phone-call page anchor

Now comes the fun part - writing Java that will handle an incoming HTTP request from Twilio!

In this example we'll use Java Servlets to respond to the Twilio webhook. We'll then use TwiML to tell Twilio how to handle the call.

Record part of an incoming call

record-part-of-an-incoming-call page anchor

Use the <Record> TwiML verb to record a message from the caller

Java

_46
import java.io.IOException;
_46
_46
import javax.servlet.ServletException;
_46
import javax.servlet.annotation.WebServlet;
_46
import javax.servlet.http.HttpServlet;
_46
import javax.servlet.http.HttpServletRequest;
_46
import javax.servlet.http.HttpServletResponse;
_46
_46
import com.twilio.twiml.*;
_46
_46
@SuppressWarnings("serial")
_46
@WebServlet("/voice")
_46
public class RecordServlet extends HttpServlet {
_46
_46
// Handle HTTP POST to /record
_46
protected void doPost(HttpServletRequest request, HttpServletResponse response)
_46
throws ServletException, IOException {
_46
// Use <Say> to give the caller some instructions
_46
Say instructions = new Say.Builder("Hello. Please leave a message after the beep.").build();
_46
_46
// Use <Record> to record the caller's message
_46
Record record = new Record.Builder().build();
_46
_46
// End the call with <Hangup>
_46
Hangup hangup = new Hangup();
_46
_46
// Create a TwiML builder object
_46
VoiceResponse twiml = new VoiceResponse.Builder()
_46
.say(instructions)
_46
.record(record)
_46
.hangup(hangup)
_46
.build();
_46
_46
// Render TwiML as XML
_46
response.setContentType("text/xml");
_46
_46
try {
_46
response.getWriter().print(twiml.toXml());
_46
} catch (TwiMLException e) {
_46
e.printStackTrace();
_46
}
_46
_46
_46
_46
}
_46
}


Record an outgoing phone call

record-an-outgoing-phone-call page anchor

When you make outgoing calls with the Twilio REST API, you can tell Twilio to record the entire call from beginning to end. But first, we'll need to get your credentials to make that request.

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 and record an outbound call

make-and-record-an-outbound-call page anchor

Just pass an extra "record" argument to "client.account.calls.create()" and Twilio will record the entire phone call.

Java

_24
// Install the Java helper library from twilio.com/docs/java/install
_24
_24
import java.net.URI;
_24
import com.twilio.Twilio;
_24
import com.twilio.rest.api.v2010.account.Call;
_24
_24
public class Example {
_24
// Find your Account SID and Auth Token at twilio.com/console
_24
// and set the environment variables. See http://twil.io/secure
_24
public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
_24
public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
_24
_24
public static void main(String[] args) {
_24
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
_24
Call call = Call.creator(
_24
new com.twilio.type.PhoneNumber("+14155551212"),
_24
new com.twilio.type.PhoneNumber("+15017122661"),
_24
URI.create("http://demo.twilio.com/docs/voice.xml"))
_24
.setRecord(true)
_24
.create();
_24
_24
System.out.println(call.getSid());
_24
}
_24
}

Output

_38
{
_38
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_38
"annotation": null,
_38
"answered_by": null,
_38
"api_version": "2010-04-01",
_38
"caller_name": null,
_38
"date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
_38
"date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
_38
"direction": "inbound",
_38
"duration": "15",
_38
"end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
_38
"forwarded_from": "+141586753093",
_38
"from": "+15017122661",
_38
"from_formatted": "(415) 867-5308",
_38
"group_sid": null,
_38
"parent_call_sid": null,
_38
"phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_38
"price": "-0.03000",
_38
"price_unit": "USD",
_38
"sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_38
"start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
_38
"status": "completed",
_38
"subresource_uris": {
_38
"notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
_38
"recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
_38
"payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
_38
"events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
_38
"siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
_38
"streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
_38
"user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
_38
"user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
_38
},
_38
"to": "+14155551212",
_38
"to_formatted": "(415) 867-5309",
_38
"trunk_sid": null,
_38
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
_38
"queue_time": "1000"
_38
}

Once the call is complete, you can listen to your recordings in your Twilio Console(link takes you to an external page) or access them directly through Twilio's REST API.

You can also gain access to the recording as soon as the call is complete by including a "StatusCallbackUrl" with your "client.account.calls.create()" command. At the end of the call, Twilio will send a request to the URL you specified and that request will include a link to the recording's audio file.

You can learn more about the "StatusCallbackUrl" parameter in the Making Calls reference docs.


That's how to record phone calls using Twilio and Java. If you'd like to learn more about what you can do with Twilio Voice and Java, check out these additional Guides:


Rate this page: