Quickstart

This guide walks you through creating a transcription configuration, submitting audio for transcription, and receiving the transcript through a webhook.

Prerequisites

Before you begin, complete the following prerequisites:

Create a Twilio account.
Record a call.
Store your Twilio credentials in environment variables.
Set up a webhook endpoint that can receive HTTP POST requests. For local development, you can use ngrok.

Create a transcription configuration

To create a transcription configuration, run the following cURL command. Replace https://example.com/transcription-webhook with the URL of your webhook endpoint.

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": "my_transcription_config",
6    "description": "Batch 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/transcription-webhook",
14        "method": "POST"
15      },
16      "participantDefaults": [
17        { "audioChannelIndex": 1, "type": "CUSTOMER" },
18        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
19      ]
20    }
21  }'

The id property in the response body contains the ID of your transcription configuration. Save it for a later step. For the full list of configuration parameters, see the Transcription Configuration resource.

Find a recording to transcribe

To find the SID of a recording, follow these steps:

Sign in to the Twilio Console and go to Products & services > Voice > Logs > Call recordings.
For the recording that you want to transcribe, click Call Details.
Save the Recording SID for the next step. It begins with RE.

Transcribe a Twilio recording

To begin transcribing a recording, run the following cURL command. Replace voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1 with the ID of your transcription configuration. Replace YOUR_RECORDING_ID with the SID of the recording that you found in the previous step.

Transcribe a Twilio Recording

1VOICE_V3_TRANSCRIPTION__CREATE_REQUEST_WITH_SOURCE_ID_OBJ=$(cat << EOF
2{
3  "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
4  "sourceId": "YOUR_RECORDING_ID"
5}
6EOF
7)
8curl -X POST "https://voice.twilio.com/v3/Transcriptions" \
9--json "$VOICE_V3_TRANSCRIPTION__CREATE_REQUEST_WITH_SOURCE_ID_OBJ" \
10-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "status": "PENDING",
3  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_5pe8jw3ahdmsh7zr06yh4d45x1",
4  "transcription": {
5    "id": "voice_transcription_5pe8jw3ahdmsh7zr06yh4d45x1",
6    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7    "status": "PENDING",
8    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
9    "sourceId": "REe3a2b046e52271b586425c61d84ca90e",
10    "audioStartedAt": "2026-03-10T19:42:16Z",
11    "conversationId": null,
12    "participants": [
13      {
14        "type": "CUSTOMER",
15        "address": "+15551234567",
16        "name": "Jane Doe",
17        "audioChannelIndex": 1
18      },
19      {
20        "type": "HUMAN_AGENT",
21        "address": "+15559876543",
22        "name": "Agent Smith",
23        "audioChannelIndex": 2
24      }
25    ],
26    "duration": null,
27    "resolvedConfiguration": {
28      "transcriptionEngine": "deepgram",
29      "speechModel": "nova-3",
30      "language": "en-US",
31      "transcriptionStatusCallback": {
32        "url": "https://example.com/transcription/callback",
33        "method": "POST",
34        "events": null
35      },
36      "conversationConfigurationId": "conv_configuration_01k1etx3jbfx88476ccja0889c",
37      "participantDefaults": [
38        {
39          "audioChannelIndex": 1,
40          "type": "CUSTOMER"
41        },
42        {
43          "audioChannelIndex": 2,
44          "type": "AI_AGENT"
45        }
46      ]
47    },
48    "createdAt": "2026-04-02T19:25:20.810012321Z",
49    "updatedAt": "2026-04-02T19:25:20.810012321Z",
50    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_5pe8jw3ahdmsh7zr06yh4d45x1"
51  }
52}

Twilio transcribes the recording asynchronously.

Receive the transcription

When transcription completes, Twilio makes a POST request to the webhook URL that you specified in your transcription configuration. The payload contains the full transcript, including per-sentence text, timing, and confidence scores. See the Webhook payload reference.

Next steps

To have Twilio transcribe all your new recordings without making an API request, attach your transcription configuration to a recording configuration in the Console.
To store your transcripts in Twilio, set a destination on your transcription configuration in the Console. This lets you use Conversation Intelligence.