# Transcription Configurations resource > \[!IMPORTANT] > > 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](https://www.twilio.com/en-us/legal/ai-terms/predictive-generative-ai-features). > > 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](/docs/configurations/transcriptions-resource), 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](/docs/usage/webhooks), set the `url` parameter within the `transcriptionStatusCallback` object to the URL of your server. * Through a **[conversation configuration](/docs/conversations/orchestrator/concepts/core)**. 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](/docs/configurations/transcriptions-resource) 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](#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](#transcription-engines-speech-models-and-languages). | | `language` | string | The language code for transcription. See [Transcription engines, speech models, and languages](#transcription-engines-speech-models-and-languages). | | `transcriptionStatusCallback` | object | Webhook to receive transcription results. See [transcriptionStatusCallback properties](#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](#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) ```bash curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "transcription_with_deepgram", "description": "Transcription configuration using Deepgram nova-3", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-3", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-3", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Transcription configuration using Deepgram nova-3", "unique_name": "transcription_with_deepgram", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ### Deepgram (`nova-2`, multilingual auto-detection) ```bash curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "transcription_with_deepgram_multilingual", "description": "Transcription configuration using Deepgram nova-2 with multilingual auto-detection", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-2", "language": "multi", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-2", "language": "multi", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Transcription configuration using Deepgram nova-2 with multilingual auto-detection", "unique_name": "transcription_with_deepgram_multilingual", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ### Google (`chirp_2`, English US) ```bash curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "transcription_with_google", "description": "Transcription configuration using Google chirp_2", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "google", "speechModel": "chirp_2", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "google", "speechModel": "chirp_2", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Transcription configuration using Google chirp_2", "unique_name": "transcription_with_google", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ### Store results in a conversation ```bash curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "transcription_with_conversation", "description": "Transcription configuration storing results in a conversation", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "language": "en-US", "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1", "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "speechModel": "twilio_managed", "language": "en-US", "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1", "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Transcription configuration storing results in a conversation", "unique_name": "transcription_with_conversation", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ### Twilio managed (automatic speech model) ```bash curl -X POST "https://voice.twilio.com/v2/Configurations/Transcription" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "transcription_with_twilio_managed", "description": "Transcription configuration using Twilio Managed engine", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "speechModel": "twilio_managed", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Transcription configuration using Twilio Managed engine", "unique_name": "transcription_with_twilio_managed", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ### 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-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 ```bash curl -X GET "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "speechModel": "twilio_managed", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "My transcription configuration", "unique_name": "my_transcription_config", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` ## List Transcription Configurations ```bash curl -X GET "https://voice.twilio.com/v2/Configurations/Transcription?pageSize=10" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" ``` ```json { "content": [ { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "twilio_managed", "speechModel": "twilio_managed", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/transcription-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "My transcription configuration", "unique_name": "my_transcription_config", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T11:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ], "meta": { "direct_token": true, "list_key": "content", "next_token": "", "page_size": 10, "previous_token": "" } } ``` > \[!NOTE] > > `pageSize` and `pageToken` are optional query parameters. ## Update a Transcription Configuration ```bash curl -X PUT "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "unique_name": "my_updated_transcription_config", "description": "Updated transcription configuration", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-3", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/updated-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] } }' ``` ```json { "account_sid": "ACxxxxxxxxxxxxxxxxxxxxx", "configuration": { "configurationType": "Transcription", "transcriptionEngine": "deepgram", "speechModel": "nova-3", "language": "en-US", "transcriptionStatusCallback": { "url": "https://example.com/updated-callback", "method": "POST" }, "participantDefaults": [ { "audioChannelIndex": 1, "type": "CUSTOMER" }, { "audioChannelIndex": 2, "type": "HUMAN_AGENT" } ] }, "description": "Updated transcription configuration", "unique_name": "my_updated_transcription_config", "date_created": "2026-04-15T11:00:00Z", "date_updated": "2026-04-15T12:00:00Z", "id": "voice_transcriptionconfiguration_xxxxxxxxx" } ``` > \[!NOTE] > > 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 ```bash curl -X DELETE "https://voice.twilio.com/v2/Configurations/Transcription/voice_transcriptionconfiguration_xxxxxxx" \ -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" ``` A successful response returns HTTP `204 No Content` with no body.