Record Calls Using Java

Overview

This guide shows how to initiating call recordings for outbound API calls, Dial XML-connected calls, and conference calls. You can record inbound calls to a Plivo number too when the application associated with the number returns an XML document with a Dial and a Record element.

Prerequisites

To get started, you need a Plivo account — sign up with your work email address if you don’t have one already. You must have a voice-enabled Plivo phone number to receive incoming calls; you can rent numbers from the Numbers page of the Plivo console, or by using the Numbers API. If this is your first time using Plivo APIs, follow our instructions to set up a Java development environment and a web server and safely expose that server to the internet.

Record a complete outbound call using XML

You can record a complete call session using the Record XML element in conjunction with a Dial element response that’s returned by an answer URL. Recording a complete call is useful in applications such as virtual voicemail boxes and automated speech surveys.

The XML might look like this:

<Response>
 <Record action="https://<yourdomain>.com/get_recording/" startOnDialAnswer="true" redirect="false" maxLength="3600" />
 <Dial>
  <Number>12025551234</Number>
 </Dial>
</Response>

When the number specified in the Dial XML element answers the call, Plivo records the complete call session. Recording details are sent to the action URL as soon as the recording starts. You can use the attributes available in the Record XML element to control the recording behavior.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.plivo.api.xml.samples.record;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Dial;
import com.plivo.api.xml.Number;
import com.plivo.api.xml.Record;
import com.plivo.api.xml.Response;

class RecordACompleteCallSession {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
            .children(
                new Record("https://<yourdomain>.com/get_recording/")
                .redirect(false)
                .startOnDialAnswer(true),
                new Dial()
                .children(
                    new Number("<phone_number>")
                )
            );
        System.out.println(response.toXmlString());
    }
}

Replace the phone number placeholder with an actual phone number (for example, 12025551234).

Record a complete conference call using XML

You can record a complete conference call initiated using a Conference XML element by using an XML response like this:

<Response>
  <Conference callbackUrl="https://<yourdomain>.com/confevents/" callbackMethod="POST" record="true" recordFileFormat="wav">My Room</Conference>
</Response>

Plivo will record the complete audio of a conference call connected via this XML document. Recording details are sent to the action URL and callback URL as soon as the recording starts. The parameter ConferenceAction=record is also sent to the callback URL when the recording starts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Example for conference
package com.plivo.api.xml.samples.conference;

import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.xml.Conference;
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;

class RecordConference {
    public static void main(String[] args) throws PlivoXmlException {
        Response response = new Response()
            .children(
                new Speak("You will now be placed into the conference"),
                new Conference("<conference_room_name>")
                .record(true)
                .callbackMethod("POST")
                .callbackUrl("https://<yourdomain>.com/confevents/")
                .waitSound("https://<yourdomain>.com/waitmusic/")
            );
        System.out.println(response.toXmlString());
    }
}

Start and stop call recording using APIs

You can start and stop voice recordings for outbound API calls, Dial XML-connected calls, and conference calls using the Record API and Record Conference API.

Record API

To start recording using the Record API, you must use the CallUUID of the particular call that you want to record.

Retrieve a CallUUID

You can get the CallUUID of a call connected via the Outbound API and Dial XML from any of these arguments:

• ring_url: Plivo sends a webhook callback to the ring URL used in the call API request as soon as the destination number starts ringing.
• answer_url: Plivo sends a webhook callback to the answer URL when the destination number answers the call.
• fallback_url: If you define the fallback URL argument in the API request or the application attached to the Plivo number, and if the application server defined in the answer URL is unavailable, then Plivo will try to retrieve the XML document from the fallback URL to process the call. At that time Plivo will send a webhook callback to the fallback URL.
• callback_url: If you use the callbackUrl parameter in the Dial XML, Plivo will send a callback to the web server configured in callback URL when the number specified in the Dial XML element answers the call.

Start recording

Once you have the CallUUID of the call you want to record, you can call the record API and specify the CallUUID in the payload.

For example, if you want to record an outbound API call, you can use the code below to record the call once the destination number answers the call. The recording will stop automatically once the call is completed.

Locate the file PlivoVoiceApplication.java in the src/main/java/com.example.demo/ folder and paste into it this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
package com.example.demo;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.call.Call;
import com.plivo.api.models.call.actions.CallRecordCreateResponse;
import com.plivo.api.xml.*;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.plivo.api.exceptions.PlivoXmlException;

import java.io.IOException;

@SpringBootApplication
@RestController
public class PlivoVoiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(PlivoVoiceApplication.class, args);
    }
    
    @GetMapping(value = "/record", produces = {
        "application/xml"
    })
    public Response recordCall() throws PlivoXmlException, IOException, PlivoRestException {
        Response resp = new Response();
        resp.children(
            new GetInput()
            .action("https://<yourdomain>.com/record_action/")
            .method("POST")
            .inputType("dtmf")
            .digitEndTimeout(5)
            .redirect(true)
            .children(
                new Speak("Press 1 to record this call")
            ));
        return resp;
    }
    
    @GetMapping(value = "/record_action", produces = {
        "application/xml"
    })
    public String forwardCall(@RequestParam("Digits") String digits, @RequestParam("CallUUID") String callUuid) throws PlivoXmlException, IOException, PlivoRestException {
        System.out.println("Digit : " + digits + " Call UUID : " + callUuid);
        Response resp = new Response();
        Plivo.init("<auth_id>", "<auth_token>");
        if (digits.equals("1")) {
            CallRecordCreateResponse r = Call.recorder(callUuid)
                .record();
            System.out.println(r);
        } else {
            System.out.println("Invalid input");
        }
        return "ok";
    }
}

Replace the auth placeholders with your authentication credentials from the Plivo console.

Stop recording

You can stop recording a call by using the CallUUID — see our API reference documentation.

Start and stop conference call recording using APIs

Record Conference API

To start recording conference calls using the Record Conference API, use the name of the conference you want to record. If you want to start recording a conference call once a participant has entered the conference room, you can use this code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package com.plivo.api.samples.conference.record;

import java.io.IOException;

import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.conference.Conference;
import com.plivo.api.models.conference.ConferenceRecordCreateResponse;

    class RecordCreate {
    public static void main(String[] args) {
        Plivo.init("<auth_id>","<auth_token>");
        try {
            ConferenceRecordCreateResponse response = Conference.recorder("<conference_room_name>")
                .record();
    
            System.out.println(response);
        } catch (PlivoRestException | IOException e) {
            e.printStackTrace();
        }
    }
    }
    

Replace the auth placeholders with your authentication credentials from the Plivo console.

Stop recording

You can stop recording a conference call by using the conference name — see our API reference documentation.

Recording features

• File formats: You can choose the recording file format (WAV or MP3) by using the file_format attribute for the Record API and Record Conference API, recordFileFormat for the Conference XML element, and fileFormat for the Record XML element.
• Channels: Plivo makes mono recordings of conference calls and stereo recordings of regular calls.
• Recording length: You can set the maximum duration of a recording by using arguments and attributes such as time_limit for the Record API and maxLength for the Record XML element.

Managing recordings

• Fetching recording details: You can store and retrieve the recording details of the voice calls and conference calls using the HTTP callbacks received on the action and callback URLs. You can also fetch recording details from the Voice > Recordings page of the Plivo console.
• Deleting recordings: You can delete a recording by using the Delete a Recording API and specifying a recording ID, which you can retrieve from the HTTP callback details stored in your database. You can also delete recordings from the Voice > Recordings page of the Plivo console.

Authentication for recordings

Recordings hosted on Plivo servers are accessible only via unique, hard to guess, long URLs that Plivo shares in recording callbacks and API responses. By default, we do not enforce authentication on GET recording media requests to allow for easy implementation of use cases that involve playing recordings on a web or mobile front end.

For enhanced security, we recommend enabling basic authentication for retrieving recording media assets in your Plivo account. You can enable Basic Auth for Recording URLs from the Voice > Other Settings page of the Plivo console.