On this page

Transcript Resource

(warning)

Warning

Public Beta

Voice Intelligence is currently available as a public beta release. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by a Twilio SLA.

Learn more about beta product support.

A Transcript resource represents a voice conversation that has automatically been converted to text through Voice Intelligence. The Transcript resource is a container and includes links to individual transcribed Sentence, Media, and OperatorResults resources.

Transcript Properties

Resource properties

account_sidtype: SID<AC>Not PII

The unique SID identifier of the Account.

service_sidtype: SID<GA>Not PII

The unique SID identifier of the Service.

sidtype: SID<GT>Not PII

A 34 character string that uniquely identifies this Transcript.

date_createdtype: string<DATE TIME>Not PII

The date that this Transcript was created, given in ISO 8601 format.

date_updatedtype: string<DATE TIME>Not PII

The date that this Transcript was updated, given in ISO 8601 format.

statustype: enum<STRING>Not PII

The Status of this Transcript. One of queued, in-progress, completed, failed or canceled.

Possible values:

queuedin-progresscompletedfailedcanceled

channeltype: objectNot PII

Media Channel describing Transcript Source and Participant Mapping

data_loggingtype: booleanNot PII

Data logging allows Twilio to improve the quality of the speech recognition & language understanding services through using customer data to refine, fine tune and evaluate machine learning models. Note: Data logging cannot be activated via API, only via www.twilio.com, as it requires additional consent.

language_codetype: stringNot PII

The default language code of the audio.

customer_keytype: stringNot PII

media_start_timetype: string<DATE TIME>Not PII

The date that this Transcript's media was started, given in ISO 8601 format.

durationtype: integerNot PII

The duration of this Transcript's source

urltype: string<URI>Not PII

The URL of this resource.

redactiontype: booleanNot PII

If the transcript has been redacted, a redacted alternative of the transcript will be available.

linkstype: object<URI MAP>Not PII

Create a new Transcript

POST https://intelligence.twilio.com/v2/Transcripts

(information)

Info

You can only create one Transcript per RecordingSid. To re-transcribe a recording, you will need to delete the original Transcript resource and create a new one.

This limitation does not apply if you are supplying a MediaUrl to create a Transcript.

Transcripts can be created in one of two ways:

Use a recording SID
If you've made a recording on Twilio and you are storing that recording on Twilio, you can make a POST request to the Transcript API and include the recording's SID as a RecordingSID parameter. Voice Intelligence will retrieve the recording from Twilio's storage and transcribe it.
Use a media URL
If you're storing a recording outside of Twilio — for example, in your own S3 bucket — or if you're transcribing a dual-channel recording that was made on another system, such as another contact center product like Amazon Connect, you can transcribe the recording by making a POST request to the Transcript API and including the MediaUrl parameter with the recording's location as its value. The URL must be accessible, either publicly or through a mechanism like a pre-signed URL.

Transcripts cannot be created for recordings made by projects with Voice Recording Encryption enabled, as Voice Intelligence is unable to decrypt those resources. We recommend offloading those recordings to your own storage and generating a pre-signed URL to supply them to the Transcript API.

Supported media formats for Transcriptions with MediaUrl

Twilio's Transcript resource using the MediaUrl parameter supports the following audio formats:

WAV (PCM-encoded)
MP3
FLAC

All these formats support both mono and stereo audio channels.

Media updload guidelines

Use one of the supported formats to ensure compatibility with the Transcript resource.
Audio processing is optimized for transcription accuracy.
Recording file size cannot be larger than 3GB for both Twilio recordings and external files.
Audio duration cannot exceed eight hours for both Twilio recordings and external files.
Sample rate should be at least 8 KHz (telephony grade). 16 KHz is the recommended sample rate for better results.

Parameters

Request body parameters

ServiceSidtype: SID<GA>Not PII

Required

The unique SID identifier of the Service.

Channeltype: objectNot PII

Required

JSON object describing Media Channel including Source and Participants

CustomerKeytype: stringNot PII

Used to store client provided metadata. Maximum of 64 double-byte UTF8 characters.

MediaStartTimetype: string<DATE TIME>Not PII

The date that this Transcript's media was started, given in ISO 8601 format.

Create Transcript

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_13// Download the helper library from https://www.twilio.com/docs/node/install
_13// Find your Account SID and Auth Token at twilio.com/console
_13// and set the environment variables. See http://twil.io/secure
_13const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13const authToken = process.env.TWILIO_AUTH_TOKEN;
_13const client = require('twilio')(accountSid, authToken);
_13
_13client.intelligence.v2.transcripts
_13                      .create({
_13                         serviceSid: 'GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_13                         channel: {}
_13                       })
_13                      .then(transcript => console.log(transcript.sid));

Output


_25{
_25  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "service_sid": "GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "sid": "GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "date_created": "2010-08-31T20:36:28Z",
_25  "date_updated": "2010-08-31T20:36:28Z",
_25  "status": "queued",
_25  "channel": {
_25    "media_properties": {
_25      "media_url": "http://foobar.test/ClusterTests/call1.wav"
_25    }
_25  },
_25  "data_logging": false,
_25  "language_code": "en-US",
_25  "media_start_time": null,
_25  "duration": 0,
_25  "customer_key": "aaaaaaaa",
_25  "url": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "redaction": true,
_25  "links": {
_25    "sentences": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sentences",
_25    "media": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media",
_25    "operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/OperatorResults"
_25  }
_25}

Specifying channel information

Channel is the object representing the media channel. It has information about the source of the media, either a Twilio recording or a 3rd party recording, and the participants information.


_34{
_34    "$schema": "https://json-schema.org/draft/2019-09/schema",
_34    "type": "object",
_34    "items": {
_34      "$ref": "#/definitions/Channel"
_34    },
_34    "definitions": {
_34      "Channel": {
_34        "type": "object",
_34        "additionalProperties": false,
_34        "properties": {
_34          "media_properties": {
_34            "type": "object",
_34            "properties": {
_34              "source_sid": {
_34                "type": "string",
_34                "$comment": "Twilio Recording Sid"
_34              },
_34              "media_url": {
_34                "type": "string",
_34                  "format": "uri",
_34                "$comment": "url to the 3rd party recording"
_34              }
_34            },
_34            "$comment": "Either source_sid or media_url is required"
_34          },
_34          "participants": {
_34            "type": "array"
_34          }
_34        },
_34        "title": "Channel"
_34      }
_34   }
_34}

If the Transcript was generated from an external recording, the Channel information would look like the following:


_10{
_10     "media_properties":{
_10        "source_sid": null,
_10        "media_url": "http://www.example.com/recording/call.wav"
_10     },
_10     "participants":[
_10
_10     ]
_10 }

Specifying participant information

By default, Voice Intelligence assumes that the left channel (channel One) is the agent and the right channel (channel Two) is the customer. The order of these channels may be inverted, depending on how your call flow works and which call leg is being recorded.

You can specify information about channel structure, as well as information about who each participant is, by passing in a URL-encoded JSON array containing information about each participant into the Participants parameter in the Channel object. The Participants array follows this JSON schema:


_48{
_48  "$schema": "http://json-schema.org/draft-06/schema#",
_48  "type": "array",
_48  "maxItems": 2,
_48  "items": {
_48    "$ref": "#/definitions/Participant"
_48  },
_48  "definitions": {
_48    "Participant": {
_48      "type": "object",
_48      "additionalProperties": false,
_48      "properties": {
_48        "channel_participant": {
_48          "type": "integer",
_48          "enum": [
_48            1,
_48            2
_48          ],
_48          "$comment": "You can only specify one participant per channel"
_48        },
_48        "user_id": {
_48          "type": "string"
_48        },
_48        "media_participant_id": {
_48          "type": "string"
_48        },
_48        "role": {
_48          "type": "string"
_48        },
_48        "full_name": {
_48          "type": "string"
_48        },
_48        "email": {
_48          "type": "string",
_48          "format": "email"
_48        },
_48        "image_url": {
_48          "type": "string",
_48          "format": "uri"
_48        }
_48      },
_48      "required": [
_48        "channel_participant"
_48      ],
_48      "title": "Participant"
_48    }
_48  }
_48}

Specifying both participants


_20[
_20      {
_20         "user_id" : "id1",
_20         "channel_participant": 1,
_20         "media_participant_id": "+1505959545",
_20         "email": "veronica.meyer@example.com",
_20         "full_name": "Veronica Meyer",
_20         "image_url": "https://images.unsplash.com/photo-1438761681033-6461ffad8d80",
_20         "role": "Agent"
_20      },
_20      {
_20         "user_id" : "id2",
_20         "channel_participant": 2,
_20         "media_participant_id": "+1505959505",
_20         "email": "lauryn.trujillo@example.com",
_20         "full_name": "Lauryn Trujillo",
_20         "image_url": "https://images.unsplash.com/photo-1554384645-13eab165c24b",
_20         "role": "Customer"
_20      }
_20]

Fetch an existing Transcript

GET https://intelligence.twilio.com/v2/Transcripts/{Sid}

Parameters

URI parameters

Sidtype: SID<GT>Not PII

Path Parameter

A 34 character string that uniquely identifies this Transcript.

Fetch a Transcript

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10
_10client.intelligence.v2.transcripts('GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10                      .fetch()
_10                      .then(transcript => console.log(transcript.serviceSid));

Output


_21{
_21  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "service_sid": "GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "sid": "GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "date_created": "2010-08-31T20:36:28Z",
_21  "date_updated": "2010-08-31T20:36:28Z",
_21  "status": "queued",
_21  "channel": {},
_21  "data_logging": false,
_21  "language_code": "en-US",
_21  "media_start_time": null,
_21  "duration": 0,
_21  "customer_key": null,
_21  "url": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21  "redaction": true,
_21  "links": {
_21    "sentences": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sentences",
_21    "media": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media",
_21    "operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/OperatorResults"
_21  }
_21}

Fetch multiple Transcripts

GET https://intelligence.twilio.com/v2/Transcripts

Parameters

URI parameters

ServiceSidtype: SID<GA>Not PII

Query Parameter

The unique SID identifier of the Service.

BeforeStartTimetype: stringNot PII

Query Parameter

Filter by before StartTime.

AfterStartTimetype: stringNot PII

Query Parameter

Filter by after StartTime.

BeforeDateCreatedtype: stringNot PII

Query Parameter

Filter by before DateCreated.

AfterDateCreatedtype: stringNot PII

Query Parameter

Filter by after DateCreated.

Statustype: stringNot PII

Query Parameter

Filter by status.

LanguageCodetype: stringNot PII

Query Parameter

Filter by Language Code.

SourceSidtype: stringNot PII

Query Parameter

Filter by SourceSid.

PageSizetype: integerNot PII

Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Pagetype: integerNot PII

Query Parameter

The page index. This value is simply for client state.

PageTokentype: stringNot PII

Query Parameter

The page token. This is provided by the API.

List multiple Transcripts

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10
_10client.intelligence.v2.transcripts
_10      .list({limit: 20})
_10      .then(transcripts => transcripts.forEach(t => console.log(t.sid)));

Output


_34{
_34  "transcripts": [
_34    {
_34      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34      "service_sid": "GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34      "sid": "GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34      "date_created": "2010-08-31T20:36:28Z",
_34      "date_updated": "2010-08-31T20:36:28Z",
_34      "status": "queued",
_34      "channel": {},
_34      "data_logging": false,
_34      "language_code": "en-US",
_34      "media_start_time": null,
_34      "duration": 0,
_34      "customer_key": null,
_34      "url": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34      "redaction": true,
_34      "links": {
_34        "sentences": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sentences",
_34        "media": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media",
_34        "operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/OperatorResults"
_34      }
_34    }
_34  ],
_34  "meta": {
_34    "key": "transcripts",
_34    "page": 0,
_34    "page_size": 50,
_34    "first_page_url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&ServiceSid=GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0",
_34    "next_page_url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&ServiceSid=GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=1",
_34    "previous_page_url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&ServiceSid=GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0",
_34    "url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&ServiceSid=GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0"
_34  }
_34}

Delete an existing Transcript

DELETE https://intelligence.twilio.com/v2/Transcripts/{Sid}

Parameters

URI parameters

Sidtype: SID<GT>Not PII

Path Parameter

A 34 character string that uniquely identifies this Transcript.

Delete a Transcript

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10
_10client.intelligence.v2.transcripts('GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10                      .remove();