For Customers building HIPAA-compliant workflows with Recordings, we require customers to enforce at least HTTP Authentication. To learn more about building for HIPAA compliance, please visit the latest requirements here.
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.
The status of the recording. Can be: processing, completed, absent or deleted. For information about more detailed statuses on in-progress recordings, check out how to Update a Recording Resource.
How the recording was created. Can be: DialVerb, Conference, OutboundAPI, Trunking, RecordVerb, StartCallRecordingAPI, and StartConferenceRecordingAPI.
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.
The URL of the media file associated with this recording resource. When stored externally, this is the full URL location of the media file.
Create a Recording resource
_10
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.
Note that the maximum length of the recording can be up to the maximum length of the Call itself.
(warning)
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 in the "Legal Considerations with Recording Voice and Video Communications" Help Center article.
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:
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.
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.
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.
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.
The audio track to record for the call. Can be: inbound, outbound or both. The default is both. inbound records the audio that is received by Twilio. outbound records the audio that is generated from Twilio. both records the audio that is received and generated by Twilio.
A boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days.
Fetch a Recording Resource's metadata in JSON format
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.mp3
You can fetch a Recording's media file by appending .wav or .mp3 to the Recording Resource's URI.
It's only possible to fetch a Recording's media file when the Recording's status is completed and the media is stored at Twilio.
If the media associated with a Recording Resource is not available/was deleted/was uploaded to external storage, the request returns Not Found.
WAV
Without an extension, or with a ".wav", a binary WAV audio file is returned with mime-type "audio/x-wav". For example:
_10
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:
_10
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3
MP3 files have a bitrate of 32kbps
Download dual-channel media file
Call and Conference Recordings are stored at Twilio in dual-channel format by default.
For a two-party Call, the Recording's dual-channel media file contains the audio from each call leg in separate channels.
For a Conference, the Recording's dual-channel media file contains the audio of the first participant that joined the Conference in the first channel and all other audio from the Call mixed in the second channel.
Note:
To access this feature, you need to enable Dual-channel Conference Recordings on the Voice Settings page in the
Console
. Read the
Dual-channel Conference Recordings Changelog entry
for more information.
When sending the GET request to download a Recording's media file, the RequestedChannels query parameter can be used to specify whether the media file should be downmixed to a single channel or if the file should be downloaded in its original, dual-channel format.
If the
RequestedChannels
query parameter is not specified when requesting the media file for a
two-party Call Recording
, Twilio returns a media file in the format specified when the Recording was created.
If the
RequestedChannels
query parameter is not specified when requesting the media file for a
Conference Recording
, Twilio returns a media file in mono-channel format.
(warning)
Warning
Attempting to download a dual-channel media file when the dual-channel format is not available results in a 400 Bad Request error. This may happen in the following cases:
A Recording created with the
<Record>
verb. All audio from those Recordings are mixed and saved in a mono-channel media file.
Older Recordings from two-party Calls or Conferences prior to dual-channel support.
To prevent application errors while managing Recordings, you should implement retry logic when sending a GET request for a Recording's media file. If a request for a dual-channel media file fails, retry with a GET request for with RequestedChannels=1.
Example: Download MP3 media in dual-channel format
Append .mp3?RequestedChannels=2 to your Recording's URL
_10
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3?RequestedChannels=2
Example: Download WAV media in dual-channel format
Append .wav?RequestedChannels=2to your Recording's URL
_10
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.wav?RequestedChannels=2
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):
_10
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
_10
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.
(warning)
Warning
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:
_10
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json
_10
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings.json
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.
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.
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.
A boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings/{Sid}.json
_10
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)
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.
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.
Pause a call recording with skip option
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_22
// Download the helper library from https://www.twilio.com/docs/node/install
_22
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22
_22
// Find your Account SID and Auth Token at twilio.com/console
_22
// and set the environment variables. See http://twil.io/secure
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 on calls with only one active recording.
(warning)
Warning
Note that if your use case has multiple or concurrent recordings for a call or conference, you will need to use the Recording SID to reference the correct one. Using Twilio.CURRENT to reference a recording on a resource that has multiple recordings will result in an error that the request failed because there is more than one recording for the given Call.
Pause a call recording with Twilio.CURRENT
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure