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.
Once a recording is initiated, you can optionally pause, resume, or stop the recording
account_sid
type: SID<AC>The SID of the Account that created the Recording resource.
^AC[0-9a-fA-F]{32}$
34
34
call_sid
type: SID<CA>The SID of the Call the Recording resource is associated with. This will always refer to the parent leg of a two-leg call.
^CA[0-9a-fA-F]{32}$
34
34
conference_sid
type: SID<CF>The Conference SID that identifies the conference associated with the recording, if a conference recording.
^CF[0-9a-fA-F]{32}$
34
34
date_created
type: string<date-time-rfc-2822>The date and time in GMT that the resource was created specified in RFC 2822 format.
date_updated
type: string<date-time-rfc-2822>The date and time in GMT that the resource was last updated specified in RFC 2822 format.
start_time
type: string<date-time-rfc-2822>The start time of the recording in GMT and in RFC 2822 format.
sid
type: SID<RE>The unique string that that we created to identify the Recording resource.
^RE[0-9a-fA-F]{32}$
34
34
status
type: enum<string>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.
in-progress
paused
stopped
processing
completed
absent
deleted
channels
type: integerThe 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
type: enum<string>How the recording was created. Can be: DialVerb
, Conference
, OutboundAPI
, Trunking
, RecordVerb
, StartCallRecordingAPI
, and StartConferenceRecordingAPI
.
DialVerb
Conference
OutboundAPI
Trunking
RecordVerb
StartCallRecordingAPI
StartConferenceRecordingAPI
error_code
type: integerThe 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
.
encryption_details
type: objectHow to decrypt the recording if it was encrypted using Call Recording Encryption feature.
subresource_uris
type: object<uri-map>A list of related resources identified by their relative URIs.
media_url
type: string<uri>The URL of the media file associated with this recording resource. When stored externally, this is the full URL location of the media file.
_10POST 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.
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.
The following optional parameters are available for you to POST
when starting a recording on a live call:
AccountSid
type: SID<AC>The SID of the Account that will create the resource.
^AC[0-9a-fA-F]{32}$
34
34
CallSid
type: SID<CA>The SID of the Call to associate the resource with.
^CA[0-9a-fA-F]{32}$
34
34
RecordingStatusCallbackEvent
type: array[string]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.
RecordingStatusCallback
type: string<uri>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.
RecordingStatusCallbackMethod
type: enum<http-method>The HTTP method we should use to call recording_status_callback
. Can be: GET
or POST
and the default is POST
.
GET
POST
Trim
type: stringWhether 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.
RecordingChannels
type: stringThe 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.
RecordingTrack
type: stringThe 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.
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 . |
RecordingTrack | The audio track recorded. Possible values are inbound , outbound or both . |
You can fetch a Recording Resource's metadata or you can fetch a WAV or MP3 media file of the Recording.
_10GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json
A Recording Resource's metadata can be returned in JSON or XML format.
.json
to the Recording Resource's URI.
.xml
to the Recording Resource's URI.
The table below lists the parameters for fetching a Recording Resource's metadata.
AccountSid
type: SID<AC>The SID of the Account that created the Recording resource to fetch.
^AC[0-9a-fA-F]{32}$
34
34
Sid
type: SID<RE>The Twilio-provided string that uniquely identifies the Recording resource to fetch.
^RE[0-9a-fA-F]{32}$
34
34
IncludeSoftDeleted
type: booleanA boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days.
_10GET 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
.
Without an extension, or with a ".wav", a binary WAV audio file is returned with mime-type "audio/x-wav". For example:
_10GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485
WAV files have a bitrate of 128kbps
Appending ".mp3" to the URI returns a binary MP3 audio file with mime-type type "audio/mpeg". For example:
_10GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3
MP3 files have a bitrate of 32kbps
Call recordings are stored at Twilio in dual-channel by default. The media file associated with the recording resource of a two-party call has two channels and contains the audio from each call leg in a separate channel. The RequestedChannels
query parameter can be used to specify whether the file should be downmixed to a single channel or if the file should be downloaded in its original, dual-channel format.
For backward compatibility, if the RequestedChannels
query parameter is not specified, the downloaded file's format will be the format that was specified when the recording was created.
For voice recordings in which dual-channel is not supported, like those created with <Conference> or <Record>, all audio from a recording will be saved in a single channel file. If a dual-channel recording is explicitly requested for download in these instances, the response will be Not Found
.
Example: Download MP3 media in dual-channel format
Append .mp3?RequestedChannels=2
to your Recording's URL
_10GET 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=2
to your Recording's URL
_10GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.wav?RequestedChannels=2
Each Recording instance resource has a Transcriptions subresource which represents the set of transcriptions generated from the recording (if any):
_10GET 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.
_10GET 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:
_10GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json_10GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings.json
AccountSid
type: SID<AC>The SID of the Account that created the Recording resources to read.
^AC[0-9a-fA-F]{32}$
34
34
DateCreated
type: string<date-time>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.
DateCreated<
type: string<date-time>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.
DateCreated>
type: string<date-time>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.
ConferenceSid
type: SID<CF>The Conference SID that identifies the conference associated with the recording to read.
^CF[0-9a-fA-F]{32}$
34
34
IncludeSoftDeleted
type: booleanA boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days.
PageSize
type: integerHow many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Page
type: integerThe page index. This value is simply for client state.
0
Examples
_10POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings/{Sid}.json_10POST 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)
AccountSid
type: SID<AC>The SID of the Account that created the Recording resource to update.
^AC[0-9a-fA-F]{32}$
34
34
Sid
type: stringThe Twilio-provided string that uniquely identifies the Recording resource to update.
Status
type: enum<string>RequiredThe new status of the recording. Can be: stopped
, paused
, in-progress
.
in-progress
paused
stopped
processing
completed
absent
PauseBehavior
type: stringWhether 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 on calls with only one active recording.
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.
_10DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json
Deletes a recording from your account. Once the recording is deleted:
deleted
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.
AccountSid
type: SID<AC>The SID of the Account that created the Recording resources to delete.
^AC[0-9a-fA-F]{32}$
34
34
Sid
type: SID<RE>The Twilio-provided string that uniquely identifies the Recording resource to delete.
^RE[0-9a-fA-F]{32}$
34
34
To to delete a large set of Voice Recordings, you can use the bulk deletion capabilities available in the Twilio Console.
Example: