Menu

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

Recording properties

account_sid
sid<AC> Not PII

The unique ID of the Account responsible for this recording.

api_version
string Not PII

The version of the API in use during the recording.

call_sid
sid<CA> Not PII

A unique identifier for the call associated with the recording. This will always refer to the parent leg of a two-leg call.

channels
integer Not PII

The number of channels in the final recording file as an integer. Possible values are 1 & 2. You may split a call with two legs into two separate recording channels if you record via TwiML Dial or the Outbound Rest API.

conference_sid
sid<CF> Not PII

The unique ID for the conference associated with the recording, if the recording is of a conference.

date_created
date_time<rfc2822> Not PII

The date that this resource was created, in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date that this resource was last updated, in RFC 2822 format.

duration
string Not PII

The length of the recording in seconds.

encryption_details
object Not PII

Details for how to decrypt the recording if encrypted via the Call Recording Encryption feature.

error_code
integer? Not PII

If the Status for this recording is failed, this will include more information about the failure. Value will be null for all other statuses.

price
string Not PII

The one-time cost of creating this recording. Example: -0.00250

price_unit
string Not PII

The currency used in the Price property. Example: USD

sid
sid<RE> Not PII

A 34 character string that uniquely identifies this resource.

source
enum:source Not PII

The initiation method used to create this recording. Possible values are: DialVerb, Conference, OutboundAPI, Trunking, RecordVerb, StartCallRecordingAPI, StartConferenceRecordingAPI

start_time
date_time<rfc2822> Not PII

The start time of the recording, in RFC 2822 format.

status
enum:status Not PII

The status of the recording. Possible values are: processing, completed, failed. For more detailed statuses on in-progress recordings, check out how to Update a Recording Resource

subresource_uris
uri_map Not PII

A dictionary of URIs for related resources

uri
uri Not PII

The URI for this resource, relative to https://api.twilio.com

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.

Optional Parameters

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

AccountSid
Required
post sid<AC> Not PII

The unique ID of the Account responsible for this recording.

CallSid
Required
post sid<CA> Not PII

The call Sid that uniquely identifies this resource

RecordingChannels
Optional
post string Not PII

Possible values: mono or dual. mono records all parties of your call into one channel. dual records a 2 party call into separate channels. Defaults to mono.

RecordingStatusCallback
Optional
post url Not PII

The URL which Twilio will make its GET or POST request to for the recording events specified in parameter RecordingStatusCallbackEvent. See RecordingStatusCallback parameters for more details.

RecordingStatusCallbackEvent
Optional
post string[] Not PII

The recording status changes that should generate a request to the URL specified in RecordingStatusCallback. Possible values: in-progress, completed, failed. To specify multiple values separate them with a space. Defaults to completed.

RecordingStatusCallbackMethod
Optional
post http_method Not PII

The HTTP method Twilio should use when making a request to the RecordingStatusCallback URL. Possible values: GET, POST. Defaults to POST.

Trim
Optional
post string Not PII

Possible values: trim-silence or do-not-trim. trim-silence will trim the silence from the beginning and end of the recording. do-not-trim will not trim the silence. Defaults to do-not-trim

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, failed.
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.
Loading Code Sample...
      
      
      
      
      Loading Code Sample...
          
          
          
          

          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.

          AccountSid
          Required
          get sid<AC> Not PII

          The unique ID of the Account responsible for this recording.

          Sid
          Required
          get sid<RE> Not PII

          The unique recording SID that identifies this resource

          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.

          Loading Code Sample...
              
              
              
              

              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

              AccountSid
              Required
              get sid<AC> Not PII

              The unique ID of the Account responsible for this recording.

              CallSid
              Optional
              get sid<CA> Not PII

              Only show recordings made during the call indicated by this call SID

              ConferenceSid
              Optional
              get sid<CF> Not PII

              The unique ID for the conference associated with the recording, if the recording is of a conference.

              DateCreated
              Optional
              get date_time_inequality<iso8601> Not PII

              Only show recordings created on the given date. Should be formatted YYYY-MM-DD. You can also specify inequality: DateCreated<=YYYY-MM-DD will return recordings generated at or before midnight on a given date, and DateCreated>=YYYY-MM-DD returns recordings generated at or after midnight on a date.

              Examples

              Loading Code Sample...
                  
                  
                  
                  
                  Loading Code Sample...
                      
                      
                      
                      
                      Loading Code Sample...
                          
                          
                          
                          
                          Loading Code Sample...
                              
                              
                              
                              

                              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

                              AccountSid
                              Required
                              post sid<AC> Not PII

                              The unique ID of the Account responsible for this recording.

                              CallSid
                              Required
                              post sid<CA> Not PII

                              The call Sid that uniquely identifies this resource

                              Sid
                              Required
                              post sid_like<RE> Not PII

                              The recording sid to update. (or use 'Twilio.CURRENT' instead of recording sid to reference current active recording)

                              Status
                              Required
                              post enum:status Not PII

                              The status to change the recording to. Possible values: stopped, paused, in-progress

                              PauseBehavior
                              Optional
                              post string Not PII

                              Only applicable when setting Status parameter to paused. Possible values: skip or silence. skip will result in no recording at all during the pause period. silence will replace the actual audio of the call with silence during the pause period. Defaults to silence

                              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.

                              Loading Code Sample...
                                  
                                  
                                  
                                  
                                  Loading Code Sample...
                                      
                                      
                                      
                                      

                                      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.

                                      Loading Code Sample...
                                          
                                          
                                          
                                          
                                          Loading Code Sample...
                                              
                                              
                                              
                                              
                                              Loading Code Sample...
                                                  
                                                  
                                                  
                                                  
                                                  Loading Code Sample...
                                                      
                                                      
                                                      
                                                      

                                                      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.

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

                                                      AccountSid
                                                      Required
                                                      delete sid<AC> Not PII

                                                      The unique ID of the Account responsible for this recording.

                                                      Sid
                                                      Required
                                                      delete sid<RE> Not PII

                                                      The unique recording SID that identifies this resource

                                                      Example

                                                      Loading Code Sample...
                                                          
                                                          
                                                          
                                                          

                                                          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.

                                                          Loading Code Sample...