Transcription Configurations resource

(new)

Legal notice and public beta

Batch Transcription Configurations use artificial intelligence or machine learning technologies. By enabling or using any of these features or functionalities within Batch Transcription Configurations, you acknowledge and agree that your use of these features or functionalities is subject to the terms of the Predictive and Generative AI/ML Features Addendum.

Batch Transcription Configurations is currently available as a Public Beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Batch Transcription Configurations is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

A Transcription Configuration resource stores settings that control how audio is transcribed, including the language, transcription engine, and status callback. When you create a Batch Transcription, you provide a transcriptionConfigurationId to specify which configuration to use.

Transcription engines, speech models, and languages

Choose a transcription engine based on your use case. Each engine supports specific speech models and languages.

Engine	Speech models	Supported languages
`deepgram`	`nova-3`, `nova-2`	`en-US`, `en-GB`, `en-AU`, `de-DE`, `fr-FR`, `it-IT`, `es-MX`, `es-ES`, `es-US`, `pt-BR`, `pt-PT`, `nl-NL`, `no-NO`, `pl-PL`, `sv-SE`, `da-DK`, `multi`
`google`	`chirp_2`	`en-US`, `en-GB`, `en-AU`, `de-DE`, `fr-FR`, `it-IT`, `es-ES`, `es-US`, `pt-BR`, `pt-PT`, `nl-NL`, `no-NO`, `pl-PL`, `sv-SE`, `da-DK`
`twilio_managed`	`twilio_managed` (set automatically)	`en-US`, `en-GB`, `en-AU`, `de-DE`, `fr-FR`, `it-IT`, `es-MX`, `es-ES`, `es-US`, `pt-BR`, `pt-PT`, `nl-NL`, `no-NO`, `pl-PL`, `sv-SE`, `da-DK`

The multi language code is available only with the deepgram engine and enables automatic language detection.

When you use the twilio_managed engine, the speechModel field is set automatically to twilio_managed and doesn't need to be specified.

Receiving transcription results

You can receive transcription results in two ways. Use one or both:

Through a status callback webhook. To receive transcription results as a webhook, set the url parameter within the transcriptionStatusCallback object to the URL of your server.
Through a conversation configuration. To associate the transcription with an existing conversation configuration and receive results through that channel, use the conversationConfigurationId parameter.

At least one of transcriptionStatusCallback or conversationConfigurationId is required when you create a Transcription Configuration. You can provide both.

Participant channel mapping

A Transcription Configuration requires exactly two participants mapped to audio channels 1 and 2. Each participant must have an audioChannelIndex of 1 or 2, and the configuration must include:

Exactly one participant with type CUSTOMER
Exactly one participant with type HUMAN_AGENT or AI_AGENT

Field	Description
`audioChannelIndex`	The audio channel assigned to this participant. Must be `1` or `2`.
`type`	The participant role. Must be `CUSTOMER`, `HUMAN_AGENT`, or `AI_AGENT`.

The participant types defined here act as defaults. When you create a Batch Transcription using this configuration, each participant's type inherits from participantDefaults unless you provide an explicit type on the transcription itself. If you specify a participant type when you create the transcription, it overrides the default for that channel.

Resource properties

Property	Type	Description
`id`	string	The unique identifier for this Transcription Configuration. Format: `voice_transcriptionconfiguration_XXXXXXXXX`.
`account_sid`	string	The SID of the Account that created this resource.
`unique_name`	string	A unique, human-readable name for this configuration. Cannot contain spaces.
`description`	string	A description of this configuration.
`configuration`	object	The transcription configuration object. See Configuration object properties.
`date_created`	string	The date and time the resource was created, in ISO 8601 format.
`date_updated`	string	The date and time the resource was last updated, in ISO 8601 format.

Configuration object properties

Property	Type	Description
`configurationType`	string	Always `Transcription`.
`transcriptionEngine`	string	The transcription engine. Possible values: `twilio_managed`, `deepgram`, `google`.
`speechModel`	string	The speech model used for transcription. Set automatically to `twilio_managed` when using the `twilio_managed` engine. See Transcription engines, speech models, and languages.
`language`	string	The language code for transcription. See Transcription engines, speech models, and languages.
`transcriptionStatusCallback`	object	Webhook to receive transcription results. See transcriptionStatusCallback properties.
`conversationConfigurationId`	string	A Maestro conversation configuration ID to associate transcription results with a conversation.
`participantDefaults`	array	Default participant configurations for each audio channel. See participantDefaults properties.

transcriptionStatusCallback properties

Property	Type	Description
`url`	string	The URL to receive the transcription status callback.
`method`	string	The HTTP method for the callback. Must be `POST`.

participantDefaults properties

Property	Type	Description
`audioChannelIndex`	integer	The audio channel assigned to this participant. Must be `1` or `2`.
`type`	string	The participant role. Possible values: `CUSTOMER`, `HUMAN_AGENT`, `AI_AGENT`.

Create a Transcription Configuration

Deepgram (`nova-3`, English US)

1curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "transcription_with_deepgram",
6    "description": "Transcription configuration using Deepgram nova-3",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "deepgram",
10      "speechModel": "nova-3",
11      "language": "en-US",
12      "transcriptionStatusCallback": {
13        "url": "https://example.com/transcription-callback",
14        "method": "POST"
15      },
16      "participantDefaults": [
17        { "audioChannelIndex": 1, "type": "CUSTOMER" },
18        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
19      ]
20    }
21  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "deepgram",
6        "speechModel": "nova-3",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Transcription configuration using Deepgram nova-3",
18    "unique_name": "transcription_with_deepgram",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T11:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

Deepgram (`nova-2`, multilingual auto-detection)

1curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "transcription_with_deepgram_multilingual",
6    "description": "Transcription configuration using Deepgram nova-2 with multilingual auto-detection",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "deepgram",
10      "speechModel": "nova-2",
11      "language": "multi",
12      "transcriptionStatusCallback": {
13        "url": "https://example.com/transcription-callback",
14        "method": "POST"
15      },
16      "participantDefaults": [
17        { "audioChannelIndex": 1, "type": "CUSTOMER" },
18        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
19      ]
20    }
21  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "deepgram",
6        "speechModel": "nova-2",
7        "language": "multi",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Transcription configuration using Deepgram nova-2 with multilingual auto-detection",
18    "unique_name": "transcription_with_deepgram_multilingual",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T11:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

Google (`chirp_2`, English US)

1curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "transcription_with_google",
6    "description": "Transcription configuration using Google chirp_2",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "google",
10      "speechModel": "chirp_2",
11      "language": "en-US",
12      "transcriptionStatusCallback": {
13        "url": "https://example.com/transcription-callback",
14        "method": "POST"
15      },
16      "participantDefaults": [
17        { "audioChannelIndex": 1, "type": "CUSTOMER" },
18        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
19      ]
20    }
21  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "google",
6        "speechModel": "chirp_2",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Transcription configuration using Google chirp_2",
18    "unique_name": "transcription_with_google",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T11:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

Store results in a conversation

1curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "transcription_with_conversation",
6    "description": "Transcription configuration storing results in a conversation",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "twilio_managed",
10      "language": "en-US",
11      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
12      "participantDefaults": [
13        { "audioChannelIndex": 1, "type": "CUSTOMER" },
14        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15      ]
16    }
17  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "twilio_managed",
6        "speechModel": "twilio_managed",
7        "language": "en-US",
8        "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
9        "participantDefaults": [
10            { "audioChannelIndex": 1, "type": "CUSTOMER" },
11            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
12        ]
13    },
14    "description": "Transcription configuration storing results in a conversation",
15    "unique_name": "transcription_with_conversation",
16    "date_created": "2026-04-15T11:00:00Z",
17    "date_updated": "2026-04-15T11:00:00Z",
18    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
19}

Twilio managed (automatic speech model)

1curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "transcription_with_twilio_managed",
6    "description": "Transcription configuration using Twilio Managed engine",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "twilio_managed",
10      "language": "en-US",
11      "transcriptionStatusCallback": {
12        "url": "https://example.com/transcription-callback",
13        "method": "POST"
14      },
15      "participantDefaults": [
16        { "audioChannelIndex": 1, "type": "CUSTOMER" },
17        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
18      ]
19    }
20  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "twilio_managed",
6        "speechModel": "twilio_managed",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Transcription configuration using Twilio Managed engine",
18    "unique_name": "transcription_with_twilio_managed",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T11:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

Request body parameters

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.

configuration required fields

Property	Type	Required	Description
`configurationType`	string	Yes	Must be `Transcription`.
`transcriptionEngine`	string	Yes	The transcription engine to use. Possible values: `twilio_managed`, `deepgram`, `google`.
`speechModel`	string	Conditional	Required for the `deepgram` and `google` engines. Omit for the `twilio_managed` engine; Twilio sets it automatically.
`language`	string	Yes	The language code for transcription.
`transcriptionStatusCallback`	object	Conditional	Required if `conversationConfigurationId` isn't provided.
`conversationConfigurationId`	string	Conditional	Required if `transcriptionStatusCallback` isn't provided.
`participantDefaults`	array	Yes	Must contain exactly two entries mapping `audioChannelIndex` 1 and 2.

Fetch a Transcription Configuration

1curl -X GET "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "twilio_managed",
6        "speechModel": "twilio_managed",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "My transcription configuration",
18    "unique_name": "my_transcription_config",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T11:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

List Transcription Configurations

1curl -X GET "https://voice.twilio.com/v2/Configurations/Transcription?pageSize=10" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

1{
2    "content": [
3        {
4            "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
5            "configuration": {
6                "configurationType": "Transcription",
7                "transcriptionEngine": "twilio_managed",
8                "speechModel": "twilio_managed",
9                "language": "en-US",
10                "transcriptionStatusCallback": {
11                    "url": "https://example.com/transcription-callback",
12                    "method": "POST"
13                },
14                "participantDefaults": [
15                    { "audioChannelIndex": 1, "type": "CUSTOMER" },
16                    { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
17                ]
18            },
19            "description": "My transcription configuration",
20            "unique_name": "my_transcription_config",
21            "date_created": "2026-04-15T11:00:00Z",
22            "date_updated": "2026-04-15T11:00:00Z",
23            "id": "voice_transcriptionconfiguration_xxxxxxxxx"
24        }
25    ],
26    "meta": {
27        "direct_token": true,
28        "list_key": "content",
29        "next_token": "",
30        "page_size": 10,
31        "previous_token": ""
32    }
33}

(information)

Info

pageSize and pageToken are optional query parameters.

Update a Transcription Configuration

1curl -X PUT "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "unique_name": "my_updated_transcription_config",
6    "description": "Updated transcription configuration",
7    "configuration": {
8      "configurationType": "Transcription",
9      "transcriptionEngine": "deepgram",
10      "speechModel": "nova-3",
11      "language": "en-US",
12      "transcriptionStatusCallback": {
13        "url": "https://example.com/updated-callback",
14        "method": "POST"
15      },
16      "participantDefaults": [
17        { "audioChannelIndex": 1, "type": "CUSTOMER" },
18        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
19      ]
20    }
21  }'

1{
2    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "deepgram",
6        "speechModel": "nova-3",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/updated-callback",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Updated transcription configuration",
18    "unique_name": "my_updated_transcription_config",
19    "date_created": "2026-04-15T11:00:00Z",
20    "date_updated": "2026-04-15T12:00:00Z",
21    "id": "voice_transcriptionconfiguration_xxxxxxxxx"
22}

(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 Transcription Configuration

1curl -X DELETE "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

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

Transcription Configurations resource

Legal notice and public beta

Transcription engines, speech models, and languages

Receiving transcription results

Participant channel mapping

Resource properties

Configuration object properties

transcriptionStatusCallback properties

participantDefaults properties

Create a Transcription Configuration

Deepgram (nova-3, English US)

Deepgram (nova-2, multilingual auto-detection)

Google (chirp_2, English US)

Store results in a conversation

Twilio managed (automatic speech model)

Request body parameters

configuration required fields

Fetch a Transcription Configuration

List Transcription Configurations

Info

Update a Transcription Configuration

Info

Delete a Transcription Configuration

Deepgram (`nova-3`, English US)

Deepgram (`nova-2`, multilingual auto-detection)

Google (`chirp_2`, English US)