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, replace https://example.com/transcription-webhook with the URL of your webhook endpoint.

Create a Transcription 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 createTranscriptionConfiguration() {
14  const transcription = await client.voice.v2.transcription.create({
15    unique_name: "my_transcription_config",
16    description: "Batch transcription configuration",
17    configuration: {
18      configurationType: "Transcription",
19      transcriptionEngine: "deepgram",
20      speechModel: "nova-3",
21      language: "en-US",
22      transcriptionStatusCallback: {
23        url: "https://example.com/transcription-webhook",
24        method: "POST",
25      },
26      participantDefaults: [
27        {
28          audioChannelIndex: 1,
29          type: "CUSTOMER",
30        },
31        {
32          audioChannelIndex: 2,
33          type: "HUMAN_AGENT",
34        },
35      ],
36    },
37  });
38
39  console.log(transcription.id);
40}
41
42createTranscriptionConfiguration();

1{
2    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3    "configuration": {
4        "configurationType": "Transcription",
5        "transcriptionEngine": "deepgram",
6        "speechModel": "nova-3",
7        "language": "en-US",
8        "transcriptionStatusCallback": {
9            "url": "https://example.com/transcription-webhook",
10            "method": "POST"
11        },
12        "participantDefaults": [
13            { "audioChannelIndex": 1, "type": "CUSTOMER" },
14            { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
15        ]
16    },
17    "description": "Batch 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_XXXXXXXXXXXXXXXXXXXXXXXXXX"
22}

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 Monitor > Logs > Voice > 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, 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.

(information)

Info

participants is optional when transcribing a Twilio Recording. If you omit it, Twilio infers participant information from the recording and call metadata.

Transcribe a Twilio Recording

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 createV3Transcriptions() {
14  const transcription = await client.voice.v3.transcriptions.create({
15    transcriptionConfigurationId:
16      "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
17    sourceId: "YOUR_RECORDING_ID",
18    participants: [
19      {
20        type: "CUSTOMER",
21        address: "+15558675310",
22        name: "Dana A.",
23        audioChannelIndex: 1,
24      },
25      {
26        type: "HUMAN_AGENT",
27        address: "+15017122661",
28        name: "Quinn N.",
29        audioChannelIndex: 2,
30      },
31    ],
32  });
33
34  console.log(transcription.status);
35}
36
37createV3Transcriptions();

1{
2  "status": "PENDING",
3  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
4  "transcription": {
5    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
6    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7    "status": "PENDING",
8    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
9    "sourceId": "YOUR_RECORDING_ID",
10    "mediaUrl": null,
11    "audioStartedAt": "2026-03-10T19:42:16Z",
12    "conversationId": null,
13    "participants": [
14      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15558675310", "name": "Dana A." },
15      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15017122661", "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-webhook",
24        "method": "POST",
25        "events": null
26      },
27      "participantDefaults": [
28        { "audioChannelIndex": 1, "type": "CUSTOMER" },
29        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
30      ]
31    },
32    "createdAt": "2026-04-02T19:25:20Z",
33    "updatedAt": "2026-04-02T19:25:20Z",
34    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
35  }
36}

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.

You can also poll for the transcription's status using its statusUrl, or list all the transcriptions on your account. For details, see Fetch a Transcription and List Transcriptions.

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.