Recording Configurations resource
Warning
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.
PCI compliance
Call recordings aren't Payment Card Industry (PCI) compliant by default. To use Voice Recordings in a PCI workflow, enable PCI Mode in the Twilio Console.
To transcribe voice recordings, use the <Transcription> TwiML noun. Native and Marketplace transcriptions aren't available when PCI Mode is enabled.
The Voice Recording Configuration resource represents recording settings associated with a voice call or conference. With the Voice Recording Configuration resource, you can apply, update, retrieve, and delete recording settings in one place. Defining and applying a Voice Recording Configuration is equivalent to using individual programmatic API parameters in your code or TwiML, but you must choose one approach or the other. A recording workflow can include either a Voice Recording Configuration ID or programmatic parameters, but not both: mixing the two affects the recording composition. To use a Voice Recording Configuration, apply the configuration ID to the recordingConfigurationId parameter of the following recording methods:
<Record>in TwiML<Dial record>in TwiML<Conference record>in TwiML<Record=true>in an outbound call using the REST APIPOSTto Recording resource of an in-progress Call SID<Start><Recording>in TwiML
Info
The Voice Recording Configuration resource is only available in the us1 region.
1curl -X POST "https://voice.twilio.com/v2/Configurations/Recording" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \3-H "Content-Type: application/json" \4-d '{5"unique_name": "my_recording_config",6"description": "My recording configuration",7"configuration": {8"configurationType": "Recording",9"compositionPolicy": {10"channels": "dual",11"trim": "trim-silence"12},13"callRecordingStatusCallback": {14"url": "https://example.com/call-recording-status",15"method": "POST",16"events": ["in-progress", "completed"]17}18}19}'
1{2"account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",3"configuration": {4"configurationType": "Recording",5"compositionPolicy": {6"channels": "dual",7"trim": "trim-silence"8},9"callRecordingStatusCallback": {10"url": "https://example.com/call-recording-status",11"method": "POST",12"events": ["in-progress", "completed"]13}14},15"description": "My recording configuration",16"unique_name": "my_recording_config",17"date_created": "2026-04-15T11:00:00Z",18"date_updated": "2026-04-15T11:00:00Z",19"id": "voice_recordingconfiguration_xxxxxxxxx"20}
| Parameter | Type | Required | Description |
|---|---|---|---|
unique_name | string | No | A unique, human-readable name for this configuration. Cannot contain spaces. |
description | string | No | A description of this configuration. |
configuration | object | Yes | The configuration object. See Configuration object properties. |
| Property | Type | Required | Description |
|---|---|---|---|
configurationType | string | Yes | Must be Recording. |
compositionPolicy | object | No | The composition configuration for recordings. See compositionPolicy properties. |
callRecordingStatusCallback | object | No | Callback configuration for individual (call) recording status. See callRecordingStatusCallback properties. |
conferenceRecordingStatusCallback | object | No | Callback configuration for conference recording status. See conferenceRecordingStatusCallback properties. |
features | array | No | The features to apply to this recording. Up to three features can be added to the features object. See features properties. |
| Property | Type | Description |
|---|---|---|
channels | string | The number of channels used in the recording. Can be: mono or dual and the default is dual. mono records all parties of the call into one channel. dual records each party of a 2-party call into separate channels. |
trim | string | 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. |
| Property | Type | Description |
|---|---|---|
url | string | The URL we should call using the method on each recording event specified in the events property of the callRecordingStatusCallback object. |
method | string | The HTTP method we should use to call call_recording_status_callback. Can be: GET or POST and the default is POST. |
events | array | The recording status events on which we should call the call_recording_status_callback URL. Can be: in-progress, completed, failed, and absent and the default is completed. Separate multiple values with a space, ex: 'in-progress completed' |
| Property | Type | Description |
|---|---|---|
url | string | The URL we should call using the method on each conference recording event specified in the events property of the conferenceRecordingStatusCallback object. |
method | string | The HTTP method we should use to call conference_recording_status_callback. Can be: GET or POST and the default is POST. |
events | array | The conference recording status events on which we should call the conference_recording_status_callback URL. Can be: in-progress, completed, failed, and absent and the default is completed. Separate multiple values with a space, ex: 'in-progress completed' |
| Property | Type | Required | Description |
|---|---|---|---|
type | string | Yes | The type of feature to apply to the recording. Possible values: transcriptionConfiguration. |
featureId | string | Yes | The ID of the feature. |
description | string | No | The description of the feature. |
Info
The Batch Transcription Configuration accepts only dual-channel recordings. Twilio stores all call recordings (where track = both) and conference recordings (with the Dual-channel Recording for Conference Console setting enabled) in a dual-channel format by default. These recordings can be transcribed regardless of whether channels is set to mono or dual.
1curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \3--data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \4--data-urlencode "To=+15558675310" \5--data-urlencode "From=+15017122661" \6--data-urlencode "Record=true" \7--data-urlencode "RecordingConfigurationId=voice_recordingconfiguration_xxxxxxxxxxxxxxxxxxxxxxxxxx"
1curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Conferences/CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/Participants.json" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \3--data-urlencode "To=+15558675310" \4--data-urlencode "From=+15017122661" \5--data-urlencode "Label=customer" \6--data-urlencode "StatusCallback=https://myapp.com/events" \7--data-urlencode "StatusCallbackEvent=ringing" \8--data-urlencode "Record=true" \9--data-urlencode "RecordingConfigurationId=voice_recordingconfiguration_xxxxxxxxxxxxxxxxxxxxxxxxxx"
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Start>4<Recording recordingConfigurationId="voice_recordingconfiguration_xxxxxxxxxxxxxxxxxxxxxxxxxx" />5</Start>6<Say>The recording has started.</Say>7</Response>
1curl -X GET "https://voice.twilio.com/v2/Configurations/Recording/voice_recordingconfiguration_xxxxxxx" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"
1{2"account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",3"configuration": {4"configurationType": "Recording",5"compositionPolicy": {6"channels": "dual",7"trim": "trim-silence"8},9"callRecordingStatusCallback": {10"url": "https://example.com/call-recording-status",11"method": "POST",12"events": ["in-progress", "completed"]13}14},15"description": "My recording configuration",16"unique_name": "my_recording_config",17"date_created": "2026-04-15T11:00:00Z",18"date_updated": "2026-04-15T11:00:00Z",19"id": "voice_recordingconfiguration_xxxxxxxxx"20}
1curl -X PUT "https://voice.twilio.com/v2/Configurations/Recording/voice_recordingconfiguration_xxxxxxx" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \3-H "Content-Type: application/json" \4-d '{5"unique_name": "my_updated_recording_config",6"description": "Updated recording configuration",7"configuration": {8"configurationType": "Recording",9"compositionPolicy": {10"channels": "mono",11"trim": "do-not-trim"12},13"callRecordingStatusCallback": {14"url": "https://example.com/updated-callback",15"method": "POST",16"events": ["completed"]17}18}19}'
1{2"account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",3"configuration": {4"configurationType": "Recording",5"compositionPolicy": {6"channels": "mono",7"trim": "do-not-trim"8},9"callRecordingStatusCallback": {10"url": "https://example.com/updated-callback",11"method": "POST",12"events": ["completed"]13}14},15"description": "Updated recording configuration",16"unique_name": "my_updated_recording_config",17"date_created": "2026-04-15T11:00:00Z",18"date_updated": "2026-04-15T12:00:00Z",19"id": "voice_recordingconfiguration_xxxxxxxxx"20}
Info
If you omit a parameter or set its value to null in the update request, Twilio either sets the value to null or returns an error, depending on whether the field is required.
1curl -X DELETE "https://voice.twilio.com/v2/Configurations/Recording/voice_recordingconfiguration_xxxxxxx" \2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"