Batch Transcription 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 Batch Transcription resource represents an asynchronous transcription job for a recorded conversation. To submit audio for transcription, call the Create a Transcription endpoint. You can transcribe Twilio Recordings using a Recording SID, or provide a direct URL to an externally hosted audio file.

Audio channel formats

Batch Transcription supports several audio formats, each suited for different needs:

Mono: a single audio channel, suitable for straightforward recordings where speaker differentiation isn't crucial.
Stereo: two channels that provide spatial sound but don't separate speakers.
Dual-channel: two distinct audio tracks in the same file, ideal for differentiating speakers such as agents and customers in call recordings. This format improves transcription accuracy and participant differentiation.

For better transcription accuracy, use dual-channel recordings, especially when speaker differentiation is important.

Transcribe a Twilio Recording

To transcribe a Twilio Recording, provide the Recording SID in the sourceId parameter.

Limits for Twilio Recording transcriptions

The recording file size must not exceed 3 GB.
Audio duration can't exceed eight hours.
Recordings shorter than two seconds aren't transcribed.
To transcribe Twilio Recordings stored in external storage, use the mediaUrl parameter. The sourceId parameter isn't supported for externally stored Twilio Recordings.
You can't transcribe encrypted Voice Recordings. Move those recordings to your own external storage, generate pre-signed URLs for the decrypted files, and use the mediaUrl parameter instead.

Transcribe an external recording

To transcribe a recording stored externally, provide the recording's URL in the mediaUrl parameter.

Batch Transcription supports both mono and stereo audio for the following formats:

WAV (PCM-encoded)
MP3
FLAC

Limits for external recordings

The maximum file size allowed is 3 GB.
The maximum audio length is eight hours.
The minimum sample rate required is 8 kHz (telephony grade). For best results, use 16 kHz.

(warning)

Warning

You must provide either sourceId or mediaUrl, but not both.

Specify participant information

Optionally, provide a participants array to identify who is on each audio channel. Each participant requires an audioChannelIndex (1 or 2) and can include a type (CUSTOMER, HUMAN_AGENT, or AI_AGENT), address, and name.

When sourceId is provided, participant data is inferred from the call metadata.

When mediaUrl is provided, participant data can't be resolved from the source and must be supplied explicitly. If the transcription result is stored in a conversation through a conversationConfigurationId, participant information is required. Without it, Twilio can't correctly attribute the transcript to conversation participants.

Create a Transcription

POST https://voice.twilio.com/v3/Transcriptions

(information)

Info

A transcriptionConfigurationId is required to create a Transcription. This ID identifies the configuration that controls transcription behavior such as engine, language, and callbacks. See the Transcription Configuration resource for details.

Create a Transcription with a Recording SID

To submit a Twilio Recording for transcription, provide the Recording SID in sourceId.

1curl -X POST https://voice.twilio.com/v3/Transcriptions \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
6    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
7    "participants": [
8      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
9      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
10    ]
11  }'

1{
2  "status": "PENDING",
3  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
4  "transcription": {
5    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
6    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "status": "PENDING",
8    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
9    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
10    "mediaUrl": null,
11    "audioStartedAt": "2026-03-10T19:42:16Z",
12    "conversationId": null,
13    "participants": [
14      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
15      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
16    ],
17    "duration": null,
18    "resolvedConfiguration": {
19      "transcriptionEngine": "deepgram",
20      "speechModel": "nova-3",
21      "language": "en-US",
22      "transcriptionStatusCallback": {
23        "url": "https://example.com/transcription/callback",
24        "method": "POST",
25        "events": null
26      },
27      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
28      "participantDefaults": [
29        { "audioChannelIndex": 1, "type": "CUSTOMER" },
30        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
31      ]
32    },
33    "createdAt": "2026-04-02T19:25:20Z",
34    "updatedAt": "2026-04-02T19:25:20Z",
35    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
36  }
37}

Create a Transcription with a media URL

To submit an externally hosted audio file for transcription, provide its URL in mediaUrl.

1curl -X POST https://voice.twilio.com/v3/Transcriptions \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
6    "mediaUrl": "https://example.com/audio/recording.wav",
7    "audioStartedAt": "2026-03-10T19:42:16Z",
8    "participants": [
9      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
10      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
11    ]
12  }'

1{
2  "status": "PENDING",
3  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_4abcde1234567890abcde12345",
4  "transcription": {
5    "id": "voice_transcription_4abcde1234567890abcde12345",
6    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "status": "PENDING",
8    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
9    "sourceId": null,
10    "mediaUrl": "https://example.com/audio/recording.wav",
11    "audioStartedAt": "2026-03-10T19:42:16Z",
12    "conversationId": null,
13    "participants": [
14      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
15      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
16    ],
17    "duration": null,
18    "resolvedConfiguration": {
19      "transcriptionEngine": "deepgram",
20      "speechModel": "nova-3",
21      "language": "en-US",
22      "transcriptionStatusCallback": {
23        "url": "https://example.com/transcription/callback",
24        "method": "POST",
25        "events": null
26      },
27      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
28      "participantDefaults": [
29        { "audioChannelIndex": 1, "type": "CUSTOMER" },
30        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
31      ]
32    },
33    "createdAt": "2026-04-02T19:25:20Z",
34    "updatedAt": "2026-04-02T19:25:20Z",
35    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_4abcde1234567890abcde12345"
36  }
37}

Receive transcription results with a webhook

To receive transcription results to a webhook, set the transcriptionStatusCallback value in your transcription configuration to a URL that you control where you can receive POST requests. When transcription processing completes, Twilio sends a POST request with the full transcript to your callback URL.

(information)

Info

A transcription is marked completed when processing succeeds, regardless of webhook delivery status. If webhook delivery ultimately fails and you haven't set a conversationConfigurationId, the transcript content is unrecoverable. For critical workloads, set a conversationConfigurationId on your Transcription Configuration as a backup. This backup stores results in a conversation configuration even if webhook delivery fails.

Webhook payload reference

The webhook request body contains the complete transcription result. The following table describes the top-level properties:

Property	Type	Description
`id`	string	The ID of the transcription job. Begins with `voice_transcription_`.
`accountId`	string	Your Twilio Account SID.
`status`	string	The status of the transcription. Either `completed` or `failed`.
`transcriptionConfigurationId`	string	The ID of the Transcription Configuration used for this transcription.
`sourceId`	string or null	The SID of the Twilio Recording, if you're transcribing a recording.
`mediaUrl`	string or null	The URL of the external audio file, if you're transcribing third-party media.
`conversationId`	string or null	The ID of the conversation, if Twilio stored the transcript. `null` for webhook-only delivery.
`duration`	integer	The audio duration, in seconds.
`participants`	array	An array of resolved participants, each with a type, address, name, and channel index.
`resolvedConfiguration`	object	The engine, model, language, and settings applied to this transcription.
`sentences`	array	The full transcript content. See the following sentence properties.
`createdAt`	datetime	The date and time the transcription job was created, in ISO 8601 format.
`updatedAt`	datetime	The date and time the status was last updated, in ISO 8601 format.

The following table describes the properties of each object in the sentences array:

Property	Type	Description
`audioChannelIndex`	integer	The audio channel. For dual-channel audio, channel `1` is typically the customer and `2` the agent.
`sentenceIndex`	integer	The position within the transcript, starting at `1`.
`participantIndex`	integer or null	The index into the `participants` array that identifies the speaker.
`languageCode`	string or null	The detected language for this sentence, in BCP-47 format. Present when you set `"language": "multi"`.
`startTimeSeconds`	number	When the sentence begins, in seconds from the audio start.
`endTimeSeconds`	number	When the sentence ends, in seconds from the audio start.
`text`	string	The transcribed text.
`confidence`	number	The confidence score, from `0.0` to `1.0`.
`words`	array	Word-level detail. See the following word properties.

The following table describes the properties of each object in the words array:

Property	Type	Description
`word`	string	The transcribed word.
`startTimeSeconds`	number	When the word begins, in seconds from the audio start.
`endTimeSeconds`	number	When the word ends, in seconds from the audio start.

Example webhook payload

The following example shows a webhook payload for a completed transcription:

1{
2  "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
3  "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "status": "completed",
5  "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
6  "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
7  "mediaUrl": null,
8  "conversationId": null,
9  "duration": 245,
10  "participants": [
11    {
12      "type": "CUSTOMER",
13      "address": "+18005550100",
14      "name": "Dana A.",
15      "audioChannelIndex": 1
16    },
17    {
18      "type": "HUMAN_AGENT",
19      "address": "+18005550101",
20      "name": "Quinn N.",
21      "audioChannelIndex": 2
22    }
23  ],
24  "resolvedConfiguration": {
25    "transcriptionEngine": "deepgram",
26    "speechModel": "nova-3",
27    "language": "en-US",
28    "transcriptionStatusCallback": {
29      "url": "https://example.com/transcription-webhook",
30      "method": "POST"
31    }
32  },
33  "sentences": [
34    {
35      "audioChannelIndex": 1,
36      "sentenceIndex": 1,
37      "participantIndex": 0,
38      "startTimeSeconds": 0.08,
39      "endTimeSeconds": 3.2,
40      "text": "Hi, I'm calling about my recent order.",
41      "confidence": 0.97,
42      "words": [
43        { "word": "Hi,", "startTimeSeconds": 0.08, "endTimeSeconds": 0.3 },
44        { "word": "I'm", "startTimeSeconds": 0.48, "endTimeSeconds": 0.72 },
45        { "word": "calling", "startTimeSeconds": 0.72, "endTimeSeconds": 1.12 },
46        { "word": "about", "startTimeSeconds": 1.12, "endTimeSeconds": 1.36 },
47        { "word": "my", "startTimeSeconds": 1.36, "endTimeSeconds": 1.52 },
48        { "word": "recent", "startTimeSeconds": 1.52, "endTimeSeconds": 1.92 },
49        { "word": "order.", "startTimeSeconds": 1.92, "endTimeSeconds": 3.2 }
50      ]
51    }
52  ],
53  "createdAt": "2026-06-15T19:42:16Z",
54  "updatedAt": "2026-06-15T19:42:45Z"
55}

Verify webhook requests

Before your application acts on a webhook, verify that Twilio sent it. Twilio signs each request with an X-Twilio-Signature header that you can validate using the server-side Twilio helper libraries. For the steps and code samples, see Webhooks security.

Webhook retry behavior

If your endpoint is unavailable or returns an error, Twilio retries the request based on the retry count and retry policy configured for your account. To control how many times Twilio retries, which failures it retries on, and the total timeout, see Webhooks connection overrides.

Fetch a Transcription

(information)

Info

Use the statusUrl from the response to poll for progress. The response includes a Retry-After header with the recommended number of seconds to wait before polling again.

GET https://voice.twilio.com/v3/Transcriptions/{transcriptionId}

1curl -X GET "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa" \
2  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

1{
2  "operationId": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
3  "status": "COMPLETED",
4  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
5  "transcription": {
6    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
7    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8    "status": "COMPLETED",
9    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
10    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
11    "mediaUrl": null,
12    "audioStartedAt": "2026-03-10T19:42:16Z",
13    "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c",
14    "participants": [
15      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
16      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
17    ],
18    "duration": 120,
19    "resolvedConfiguration": {
20      "transcriptionEngine": "deepgram",
21      "speechModel": "nova-3",
22      "language": "en-US",
23      "transcriptionStatusCallback": {
24        "url": "https://example.com/transcription/callback",
25        "method": "POST",
26        "events": null
27      },
28      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
29      "participantDefaults": [
30        { "audioChannelIndex": 1, "type": "CUSTOMER" },
31        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
32      ]
33    },
34    "createdAt": "2026-04-02T19:25:20Z",
35    "updatedAt": "2026-04-02T19:25:20Z",
36    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
37  }
38}