Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Recording

A Recording resource represents the recording associated with a voice call, conference, or SIP Trunk. Using the Recordings REST API you can fetch, start, stop, pause, resume, and delete voice recordings.

You can initiate a recording for your call, conference, or trunk via one of the following methods.

  1. <Record> in TwiML
  2. <Dial record> in TwiML
  3. <Conference record> in TwiML
  4. Record=true in an outbound call via the REST API
  5. Enable recording on an elastic SIP Trunk in the Twilio Console
  6. Post to Recording resource of an in-progress Call SID

Once a recording is initiated, you can optionally pause, resume, or stop the recording

Recording properties

Names in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created the Recording resource.

api_version
string Not PII

The API version used during the recording.

call_sid
sid<CA> Not PII

The SID of the Call the Recording resource is associated with. This will always refer to the parent leg of a two-leg call.

conference_sid
sid<CF> Not PII

The Conference SID that identifies the conference associated with the recording, if a conference recording.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

start_time
date_time<rfc2822> Not PII

The start time of the recording in GMT and in RFC 2822 format.

duration
string Not PII

The length of the recording in seconds.

sid
sid<RE> Not PII

The unique string that that we created to identify the Recording resource.

price
string Not PII

The one-time cost of creating the recording in the price_unit currency.

price_unit
string Not PII

The currency used in the price property. Example: USD.

status
enum:status Not PII

The status of the recording. Can be: processing, completed and absent. For information about more detailed statuses on in-progress recordings, check out how to Update a Recording Resource.

channels
integer Not PII

The number of channels in the final recording file. Can be: 1 or 2. You can split a call with two legs into two separate recording channels if you record using TwiML Dial or the Outbound Rest API.

source
enum:source Not PII

How the recording was created. Can be: DialVerb, Conference, OutboundAPI, Trunking, RecordVerb, StartCallRecordingAPI, and StartConferenceRecordingAPI.

error_code
integer? Not PII

The error code that describes why the recording is absent. The error code is described in our Error Dictionary. This value is null if the recording status is not absent.

uri
uri Not PII

The URI of the resource, relative to https://api.twilio.com.

encryption_details
object Not PII

How to decrypt the recording if it was encrypted using Call Recording Encryption feature.

subresource_uris
uri_map Not PII

A list of related resources identified by their relative URIs.

Create a Recording resource

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallsSid}/Recordings.json

To start a recording on a live call, make an HTTP Post request to the Recordings list resource of an in-progress Call.

Legal implications of call recording

If you choose to record voice or video 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.

Optional Parameters

The following optional parameters are available for you to POST when starting a recording on a live call:

Names in REST API format
account_sid
Path
post sid<AC> Not PII

The SID of the Account that will create the resource.

call_sid
Path
post sid<CA> Not PII

The SID of the Call to associate the resource with.

recording_status_callback_event
Optional
post string[] Not PII

The recording status events on which we should call the recording_status_callback URL. Can be: in-progress, completed and absent and the default is completed. Separate multiple event values with a space.

recording_status_callback
Optional
post url Not PII

The URL we should call using the recording_status_callback_method on each recording event specified in recording_status_callback_event. For more information, see RecordingStatusCallback parameters.

recording_status_callback_method
Optional
post http_method Not PII

The HTTP method we should use to call recording_status_callback. Can be: GET or POST and the default is POST.

trim
Optional
post string Not PII

Whether to trim any leading and trailing silence in the recording. Can be: trim-silence or do-not-trim and the default is do-not-trim. trim-silence trims the silence from the beginning and end of the recording and do-not-trim does not.

recording_channels
Optional
post string Not PII

The number of channels used in the recording. Can be: mono or dual and the default is mono. mono records all parties of the call into one channel. dual records each party of a 2-party call into separate channels.

RecordingStatusCallback

Twilio will pass the following parameters with its request to your RecordingStatusCallback URL:

Parameter Description
AccountSid The unique identifier of the Account responsible for this recording.
CallSid A unique identifier for the call associated with the recording.
RecordingSid The unique identifier for the recording.
RecordingUrl The URL of the recorded audio.
RecordingStatus The status of the recording. Possible values are: in-progress, completed, absent.
RecordingDuration The length of the recording, in seconds. (only provided when RecordingStatus is completed)
RecordingChannels The number of channels in the final recording file as an integer. Possible values are 1, 2.
RecordingStartTime The timestamp of when the recording started.
RecordingSource The initiation method used to create this recording. For recordings initiated with this API, the value will be StartCallRecordingAPI.
        
        
        
        
              
              
              
              

              Fetch a Recording resource

              GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json

              Because the URLs that host individual recordings are useful for many external applications, they are public and do not require HTTP Basic Auth to access. This allows you to embed the recording URL in a web application without revealing your Twilio API credentials.

              Twilio's recording URLs are quite long and difficult to guess, so the contents of the recordings should be reasonably private unless you distribute the URL. For added security, you can enforce HTTP basic auth to access media using your AccountSid and Authentication token via the voice settings page in the console.

              Names in REST API format
              account_sid
              Path
              get sid<AC> Not PII

              The SID of the Account that created the Recording resource to fetch.

              sid
              Path
              get sid<RE> Not PII

              The Twilio-provided string that uniquely identifies the Recording resource to fetch.

              Fetch recording metadata

              Recordings Resource Metadata can be returned in either json or xml by appending the either the '.json' or 'xml' suffix to the URI.

                    
                    
                    
                    

                    Fetch a recording media file

                    WAV

                    Without an extension, or with a ".wav", a binary WAV audio file is returned with mime-type "audio/x-wav". For example:

                    GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485
                    

                    WAV files have a bitrate of 128kbps

                    MP3

                    Appending ".mp3" to the URI returns a binary MP3 audio file with mime-type type "audio/mpeg". For example:

                    GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3
                    

                    MP3 files have a bitrate of 32kbps

                    Fetch a Recording's Transcriptions

                    Each Recording instance resource has a Transcriptions subresource which represents the set of transcriptions generated from the recording (if any):

                    GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{RecordingSid}/Transcriptions

                    This will return the set of transcriptions available for the recording identified by {RecordingSid}. See the Transcriptions resource documentation for properties and response formats.

                    Read multiple Recording Resources

                    GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings.json

                    This API call returns a list of Recordings, each representing a recording generated during a call or conference for the given account. The list returned includes paging information.

                    The list of Recordings is protected by your account credentials like most parts of this API. You must use HTTP basic auth to access the Recordings list resource.

                    You can also get a list of Recordings from a specific call or conference by including the call or conference SID in your request like so:

                    GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json
                    GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings.json

                    Parameters

                    Names in REST API format
                    account_sid
                    Path
                    get sid<AC> Not PII

                    The SID of the Account that created the Recording resources to read.

                    date_created
                    Optional
                    get date_time_inequality<iso8601> Not PII

                    Only include recordings that were created on this date. Specify a date as YYYY-MM-DD in GMT, for example: 2009-07-06, to read recordings that were created on this date. You can also specify an inequality, such as DateCreated<=YYYY-MM-DD, to read recordings that were created on or before midnight of this date, and DateCreated>=YYYY-MM-DD to read recordings that were created on or after midnight of this date.

                    call_sid
                    Optional
                    get sid<CA> Not PII

                    The Call SID of the resources to read.

                    conference_sid
                    Optional
                    get sid<CF> Not PII

                    The Conference SID that identifies the conference associated with the recording to read.

                    Examples

                          
                          
                          
                          
                                
                                
                                
                                
                                      
                                      
                                      
                                      
                                            
                                            
                                            
                                            

                                            Update a Recording resource

                                            POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings/{Sid}.json
                                            POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings/{Sid}.json

                                            An active call or conference recording can be paused and resumed. Additionally, an active call recording can be stopped which will end the recording immediately. (stopped not supported for conference recordings)

                                            Parameters

                                            Names in REST API format
                                            account_sid
                                            Path
                                            post sid<AC> Not PII

                                            The SID of the Account that created the Recording resource to update.

                                            call_sid
                                            Path
                                            post sid<CA> Not PII

                                            The Call SID of the resource to update.

                                            sid
                                            Path
                                            post sid_like<RE> Not PII

                                            The Twilio-provided string that uniquely identifies the Recording resource to update.

                                            status
                                            Required
                                            post enum:status Not PII

                                            The new status of the recording. Can be: stopped, paused, in-progress.

                                            pause_behavior
                                            Optional
                                            post string Not PII

                                            Whether to record during a pause. Can be: skip or silence and the default is silence. skip does not record during the pause period, while silence will replace the actual audio of the call with silence during the pause period. This parameter only applies when setting status is set to paused.

                                            Examples:

                                            Note in examples below that the API responses for updates to the recording resource will provide a more detailed inflight 'status' including paused, in-progress, or stopped but a fetch on the recording resource will only show processing or completed.

                                                  
                                                  
                                                  
                                                  
                                                        
                                                        
                                                        
                                                        

                                                        In the following two examples, note the use of Twilio.CURRENT to reference the currently active recording without requiring an explicit Recording SID.

                                                        Twilio.CURRENT can be used for pause, resume, or stop actions. Note that if your use case has multiple or concurrent recordings for a call or conference, use the Recording SID to reference the correct one.

                                                              
                                                              
                                                              
                                                              
                                                                    
                                                                    
                                                                    
                                                                    
                                                                          
                                                                          
                                                                          
                                                                          
                                                                                
                                                                                
                                                                                
                                                                                

                                                                                Delete a Recording resource

                                                                                DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json

                                                                                Deletes a recording from your account. Once the recording is deleted:

                                                                                • You will no longer be billed for storage of those minutes
                                                                                • The recording is set to a status of deleted
                                                                                • The metadata is preserved for a period of 40 days, during which time the metadata is still visible in the Console.

                                                                                If successful, DELETE returns HTTP 204 (No Content) with no body.

                                                                                Please note that only completed recordings can be deleted. Recordings with any other status are not available for deletion.

                                                                                Names in REST API format
                                                                                account_sid
                                                                                Path
                                                                                delete sid<AC> Not PII

                                                                                The SID of the Account that created the Recording resources to delete.

                                                                                sid
                                                                                Path
                                                                                delete sid<RE> Not PII

                                                                                The Twilio-provided string that uniquely identifies the Recording resource to delete.

                                                                                To to delete a large set of Voice Recordings, you can use the bulk deletion capabilities available in the Twilio Console.

                                                                                Example:

                                                                                      
                                                                                      
                                                                                      
                                                                                      
                                                                                      Rate this page:

                                                                                      Need some help?

                                                                                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.