Getting Started with Call Recording Controls – Twilio Support

Twilio Programmable Voice calls now allow you to start, pause, and stop recording via REST API requests - all while on an active call. Below is a simple introduction for getting started with Twilio Call Recording Controls. For complete documentation, including Helper Library code samples, please refer to the Recording API reference (Twilio Docs).

Notice: All Outbound Twilio Programmable Voice calls can be recorded from the start by calling out the recording parameters and attributes in your initial API request or <Dial> TwiML. Call recordings initiated this way can be modified using the API requests outlined here.
Incoming calls also be recorded using the Call Recording Controls API, without the need for a <Dial> command.

Recording Controls

The following recording controls are supported:

Begin recording an in-progress call
Pause or resume an in-progress recording
Permanently end an in-progress recording
Pause or resume an in-progress conference recording

Begin Recording an In-progress Call

To start recording a live call - either incoming or outgoing - make an HTTP POST request to the call’s Recordings List subresource. Here’s an example cURL script:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings.json \
--data-urlencode "RecordingStatusCallback=https://myapp.com/recording-events" \
--data-urlencode "RecordingStatusCallbackEvent=in-progress completed absent" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will begin recording call CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, and tells Twilio to make an HTTP request to your included RecordingStatusCallback webhook url with all of the recording file's details when recording begins, and then again when it is posted and available for access or if no recording is created.. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with a valid Account SID and active Call SID
Line 2 update with your application site for Recording status callbacks (optional)
Note: Recording status callbacks are recommended for gathering the required Call and Recording SIDs for pausing, restarting, and ending active recordings.
Line 4 update with your Account SID and Auth Token

Additional optional parameters for call recording can be added in your request as well, including dual-channel recording, and silence trimming. For full details on the available recording options, including Helper Library (SDK) code samples, please see Create a Recording Resource (Twilio Docs).

Pause or Resume an In-progress Recording

Once a live call is being recorded, the recording can be paused and restarted via HTTP POST requests to the call’s Recording subresource. Here’s an example cURL script:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
-d "Status=XXXXX" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will update the status for recording REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with a valid Account SID, active Call SID, and recording SID
Note: This information can be found in the RecordingStatusCallback requested when the recording was initiated.
Line 2 update with the desired recording status change: paused or in-progress
Line 3 update with your Account SID and Auth Token

Additional optional parameters can be added in your request to control the audio playback of a call recording that is paused. For full details on the available recording options, including Helper Library (SDK) code samples, please see Update a Recording Resource (Twilio Docs).

Notice: The use of the full recording resource URI in Line 1 is required to update the status of any recording from a call with two or more active recordings.
For calls with only one active call recording, users can alternatively substitute Twilio.CURRENT for the live call’s recording SID in the resource URI. To use Twilio.CURRENT, make the following modification to the end of Line 1: ...Recordings/Twilio.CURRENT.json \

End an In-progress Recording

A live call recording can be ended via HTTP POST requests to the call’s Recording subresource. Here’s an example cURL script:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
-d "Status=stopped" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will end the recording REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with a valid Account SID, active Call SID, and recording SID
Note: This information can be found in the RecordingStatusCallback requested when recording was initiated.
Line 3 update with your Account SID and Auth Token

This action immediately ends the recording, and sends the file to processing. A stopped recording can’t be restarted; users needing to continue recording should be using the paused/in-progress status values, or can begin a new recording for this call with the Begin Recording an Active Call process outlined above. For full details, including Helper Library (SDK) code samples, please see Update a Recording Resource (Twilio Docs).

Notice: The use of the full recording resource URI in Line 1 is required to update the status of any recording from a call with two or more active recordings.
For calls with only one active call recording, users can substitute Twilio.CURRENT for the live call’s recording SID in the resource URI. To use Twilio.CURRENT, make the following modification to the end of Line 1: ...Recordings/Twilio.CURRENT.json \

Conference Recording Controls

Conference recordings can be paused and resumed in the same way as regular calls. The only difference is instead of making your HTTP POST requests to the active call’s subresources, your requests would go to the active conference’s subresources. Everything else stays the same, including the availability of Twilio.CURRENT. Here are some example cURL scripts:

Pause an in-progress conference recording:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conferences/CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
-d "Status=paused" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

Resume a paused conference recording:

curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Conferences/CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \
-d "Status=in-progress" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

Notice: Initiating a conference recording needs to be requested in the TwiML <Conference> noun attributes, and is not supported via the Call Recording Controls API. You can, however, start recording an in-progress call that connects to the conference using API described earlier.

Ending a conference recording that was requested in the <Conference> TwiML is also unsupported via the Call Recording Controls API, and will occur automatically when the conference ends. Users can, however, pause recording until the conference ends.

Legal Implications of Call Recording

If you choose to record calls, you need to comply with certain laws and regulations, including those regarding obtaining consent to record (such as California’s Invasion of Privacy Act and similar laws in other jurisdictions). Additional information on the legal implications of call recording can be found here.

Notice: Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Twilio.

Additional Resources