Recording Account Default Configuration resource

(warning)

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.

(information)

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.

Overview

The Voice Recording Account Default Configuration resource defines the default recording settings for all voice calls and conferences that originate from an account. You can create, update, retrieve, and delete these default settings in one place. After you create a Voice Recording Account Default Configuration, the recording settings automatically apply to every applicable call on the account — no TwiML or code changes are required. Each account can have only one Voice Recording Account Default Configuration.

To override the settings in the Voice Recording Account Default Configuration, either:

Set recording attributes programmatically (through the API or in TwiML), or
Reference a Voice Recording Configuration

Note: A single recording workflow cannot combine programmatic recording attributes with a Voice Recording Configuration ID.

(information)

Info

The Voice Recording Account Default Configuration resource is only available in the us1 region.

Create a Recording Account Default Configuration

To create a Recording Account Default Configuration, send a POST request to the AccountDefaultConfiguration/Recording endpoint. Accounts can only create a Recording Account Default Configuration once. To change a Recording Account Default Configuration, use the Update command.

Create a Recording Account Default Configuration

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createAccountDefaultConfiguration() {
14  const accountDefaultConfiguration = await client.voice.v2
15    .accountDefaultConfiguration("Recording")
16    .create({
17      description: "My recording account default configuration",
18      configuration: {
19        configurationType: "Recording",
20        compositionPolicy: {
21          channels: "dual",
22          trim: "trim-silence",
23          track: "both",
24        },
25        callRecordingStatusCallback: {
26          url: "https://example.com/call-recording-status",
27          method: "POST",
28          events: ["in-progress", "completed"],
29        },
30        features: [
31          {
32            type: "transcriptionConfiguration",
33            featureId:
34              "voice_transcriptionconfiguration_XXXXXXXXXXXXXXXXXXXXXXXXXX",
35            description: "Transcription configuration using Deepgram model",
36          },
37        ],
38      },
39    });
40
41  console.log(accountDefaultConfiguration.accountSid);
42}
43
44createAccountDefaultConfiguration();

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Recording",
5        "compositionPolicy": {
6            "channels": "dual",
7            "trim": "trim-silence",
8            "track": "both"
9        },
10        "callRecordingStatusCallback": {
11            "url": "https://example.com/call-recording-status",
12            "method": "POST",
13            "events": ["in-progress", "completed"]
14        },
15       "features": [
16            {
17                "description": "Transcription configuration using Deepgram model",
18                "featureId": "voice_transcriptionconfiguration_XXXXXXXXXXXX",
19                "type": "transcriptionConfiguration"
20            }
21        ]
22    },
23    "description": "My recording account default configuration",
24    "date_created": "2026-04-15T11:00:00Z",
25    "date_updated": "2026-04-15T11:00:00Z"
26}

Request body parameters

Parameter	Type	Required	Description
`description`	string	No	A description of this configuration.
`configuration`	object	Yes	The configuration object. See Configuration object properties.

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.

compositionPolicy 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.
`track`	string	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.

callRecordingStatusCallback properties

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`. Provide multiple values as an array, for example: `["in-progress", "completed"]`.

conferenceRecordingStatusCallback properties

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`. Provide multiple values as an array, for example: `["in-progress", "completed"]`.

features properties

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.

(information)

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.

Retrieve a Recording Account Default Configuration

To retrieve a Recording Account Default Configuration, send a GET request to AccountDefaultConfiguration/Recording

Retrieve a Recording Account Default Configuration

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchAccountDefaultConfiguration() {
14  const accountDefaultConfiguration = await client.voice.v2
15    .accountDefaultConfiguration("Recording")
16    .fetch();
17
18  console.log(accountDefaultConfiguration.accountSid);
19}
20
21fetchAccountDefaultConfiguration();

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Recording",
5        "compositionPolicy": {
6            "channels": "dual",
7            "trim": "trim-silence",
8            "track": "both"
9        },
10        "callRecordingStatusCallback": {
11            "url": "https://example.com/call-recording-status",
12            "method": "POST",
13            "events": ["in-progress", "completed"]
14        },
15        "features": [
16              {
17                "description": "Transcription configuration using Deepgram model",
18                "featureId": "voice_transcriptionconfiguration_XXXXXXXXXXXX",
19                "type": "transcriptionConfiguration"
20              }
21        ]
22    },
23    "description": "My recording account default configuration",
24    "date_created": "2026-04-15T11:00:00Z",
25    "date_updated": "2026-04-15T11:00:00Z"
26}

Update a Recording Account Default Configuration

To update a Recording Account Default Configuration, send a PUT request with the new values.

Update a Recording Account Default Configuration

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function updateAccountDefaultConfiguration() {
14  const accountDefaultConfiguration = await client.voice.v2
15    .accountDefaultConfiguration("Recording")
16    .update({
17      description: "Updated recording account default configuration",
18      configuration: {
19        configurationType: "Recording",
20        compositionPolicy: {
21          channels: "mono",
22          trim: "do-not-trim",
23          track: "outbound",
24        },
25        callRecordingStatusCallback: {
26          url: "https://example.com/updated-callback",
27          method: "POST",
28          events: ["completed"],
29        },
30      },
31    });
32
33  console.log(accountDefaultConfiguration.accountSid);
34}
35
36updateAccountDefaultConfiguration();

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Recording",
5        "compositionPolicy": {
6            "channels": "mono",
7            "trim": "do-not-trim",
8            "track": "outbound"
9        },
10        "callRecordingStatusCallback": {
11            "url": "https://example.com/updated-callback",
12            "method": "POST",
13            "events": [ "completed"]
14        }
15    },
16    "description": "Updated recording account default configuration",
17    "date_created": "2026-04-15T11:00:00Z",
18    "date_updated": "2026-04-15T11:00:00Z"
19}

(information)

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.

Delete a Recording Account Default Configuration

To delete a Recording Account Default Configuration, send a DELETE request to AccountDefaultConfiguration/Recording.

Delete a Recording Account Default Configuration

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function deleteAccountDefaultConfiguration() {
14  await client.voice.v2.accountDefaultConfiguration("Recording").remove();
15}
16
17deleteAccountDefaultConfiguration();

A successful response returns HTTP 204 No Content with no body.