With the Call Recording Controls API, it is now possible to record incoming Twilio Programmable Voice calls. Previously, Call Recording needed to be called out in the outgoing call’s API request, or in TwiML, meaning incoming Programmable Voice calls could only be recorded when a <Dial> TwiML command was used. With Call Recording controls, now users can start, pause and resume, and end a call recording - all with a simple API request.
Notice: Recording an incoming call is only supported on upgraded Twilio projects; this feature is not available for free trial projects. For more information about trial project limitations, please see How does Twilio's Free Trial work. For help upgrading your Twilio project, please see Upgrading to a paid Twilio Account.
Requirements
In order to begin recording or modify the recording status, you first need to capture the Twilio Call SID. This is automatically delivered to your webhook as the CallSid parameter value in Twilio’s HTTP request to your webhook. Your webhook will then respond to Twilio with the TwiML for running the incoming call.
Notice: You won’t be able to begin recording the call until Twilio receives and processes your TwiML response. Since your application will receive the Call SID prior to this, it’s possible that an API request to begin recording your call can be submitted too early, resulting in an error. To minimize this possibility, we recommend instituting a delay before submitting your API request, and/or retrying your record requests if they fail.
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, please see Create a Recording Resource (Twilio Docs).
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.