Modify Calls In Progress With Java

Learn to modify live phone calls and change active call execution with Twilio Programmable Voice and your Java web application by using the Twilio SDKs to send a POST request to update an active Call resource. You can use this guide to implement call center operations, build interactive voice response systems, handle dynamic call routing, and manage active call sessions.

See Related reference documentation to learn more about the Call resource and state management parameters used in this guide.

We'll use Twilio's Java SDK in these examples to interact with the Twilio REST API's Calls endpoint.

Modifying Twilio phone calls in progress with Java

The simplest way to control the flow of a Twilio phone call is with TwiML itself.

You can use the "action" parameters of verbs like <Gather> and <Record> to tell Twilio to get new instructions from your applications during a call. You can also use the <Redirect> verb to explicitly tell Twilio to fetch new TwiML.

But sometimes you need to change a live phone call outside of Twilio's normal request-response cycle. For those cases you can update the Call to tell Twilio to immediately change the TwiML it's using in a phone call.

Update an in progress Call with new TwiML instructions

1// Install the Java helper library from twilio.com/docs/java/install
2
3import com.twilio.type.Twiml;
4import com.twilio.Twilio;
5import com.twilio.rest.api.v2010.account.Call;
6
7public 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.updater("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
16                        .setTwiml(new com.twilio.type.Twiml("<Response><Say>Ahoy there</Say></Response>"))
17                        .update();
18
19        System.out.println(call.getSid());
20    }
21}

Response

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

In order to update the call you will need to use the CallSid. Twilio returns this when you initiate an outgoing call, and also includes the CallSid in its request to your application for an incoming call's initial TwiML.

As an alternative to updating your call with TwiML directly, you may also redirect a Call to a new URL that responds with your requested TwiML.

Redirect an in progress Call to a new URL

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

Response

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

Hanging up a call in progress

Twilio will end phone calls for you when it encounters a <Hangup> verb or when it runs out of TwiML to process. But you can also end phone calls whenever you like by passing a "completed" status to a CallSid in progress.

Terminate a Running Call

1// Install the Java helper library from twilio.com/docs/java/install
2
3import com.twilio.Twilio;
4import com.twilio.rest.api.v2010.account.Call;
5
6public class Example {
7    // Find your Account SID and Auth Token at twilio.com/console
8    // and set the environment variables. See http://twil.io/secure
9    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
10    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
11
12    public static void main(String[] args) {
13        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
14        Call call = Call.updater("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").setStatus(Call.UpdateStatus.COMPLETED).update();
15
16        System.out.println(call.getTo());
17    }
18}

Response

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

Check out Modifying Live Calls in the reference docs for more details.

Use cases for modifying live calls with Twilio Programmable Voice

See use cases for modifying live calls with Twilio Programmable Voice to learn about the different applications you can build with this feature.

Result

After following this guide, you can programmatically modify live phone calls using Twilio Programmable Voice and the Twilio SDKs. You will have built code that can dynamically update call directions or explicitly update the call status to complete active sessions on your account.

Next steps

Explore the following guides to build on what you've learned in this guide:

Make outbound phone calls: Learn how to spin up completely new outbound calls from your web application.
Respond to incoming phone calls: Learn how to handle incoming webhooks from Twilio to start initial phone call routines.