Skip to contentSkip to navigationSkip to topbar
On this page

Transcription Viewer Integration Guide


This guide explains how to integrate and use the Transcription Viewer single-page application in an existing web application. The Transcription Viewer single-page application allows users to to view an individual Transcript in detail.

(information)

Info

In past pre-release documentation, the Transcription Viewer single-page application was called Annotator or Conversation Viewer. The old name is still used in some places, such as app retrieval URLs.

The Voice Intelligence Transcription Viewer single-page application UI. A panel shows the complete text of a Transcript.

You can embed the single-page application's UI into an existing web app or render it in a new window. In both cases, the app requests the single-page application's code by calling a specific URL with an authorization token.

A sample implementation of the single-page application(link takes you to an external page) is available on GitHub for reference.


Prerequisites

prerequisites page anchor

Before beginning this guide, complete these steps:


The following steps explain how to integrate the Transcription Viewer single-page application into a web app and display a single Transcript.

Step 1: Identify the Transcript's SID

step-1-identify-the-transcripts-sid page anchor

First, identify the SID of the Transcript that the Transcript Viewer single-page application will display. You can get the Transcript SID in multiple ways.

Option 1: Fetch a Transcript's SID by Recording SID via API

option-1-fetch-a-transcripts-sid-by-recording-sid-via-api page anchor

If you know the SID of the Recording that generated the Transcript, then you can find the Transcript's SID by calling the Fetch Multiple Transcripts endpoint and passing the SourceSid as a query parameter to the Recording SID. The response includes a sid key with the Transcript's SID, shown as GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX in the example below.

Fetch a Transcript by Recording SIDLink to code sample: Fetch a Transcript by Recording SID
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listTranscript() {
11
const transcripts = await client.intelligence.v2.transcripts.list({
12
sourceSid: "REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
13
limit: 20,
14
});
15
16
transcripts.forEach((t) => console.log(t.accountSid));
17
}
18
19
listTranscript();

Output

1
{
2
"transcripts": [
3
{
4
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"service_sid": "GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
"sid": "GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
"date_created": "2010-08-31T20:36:28Z",
8
"date_updated": "2010-08-31T20:36:28Z",
9
"status": "queued",
10
"channel": {},
11
"data_logging": false,
12
"language_code": "en-US",
13
"media_start_time": null,
14
"duration": 0,
15
"customer_key": null,
16
"url": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
"redaction": true,
18
"links": {
19
"sentences": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sentences",
20
"media": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media",
21
"operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OperatorResults"
22
}
23
}
24
],
25
"meta": {
26
"key": "transcripts",
27
"page": 0,
28
"page_size": 50,
29
"first_page_url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&ServiceSid=GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0",
30
"next_page_url": null,
31
"previous_page_url": null,
32
"url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&ServiceSid=GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0"
33
}
34
}

Option 2: Fetch all Transcripts via API

option-2-fetch-all-transcripts-via-api page anchor

If a Recording SID isn't available, call the Fetch Multiple Transcripts endpoint without the SourceSid query parameter. This will return all Transcripts associated with the Twilio Account. The response includes a sid key with a Transcript's SID, shown as GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX in the example below.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function listTranscript() {
11
const transcripts = await client.intelligence.v2.transcripts.list({
12
limit: 20,
13
});
14
15
transcripts.forEach((t) => console.log(t.accountSid));
16
}
17
18
listTranscript();

Output

1
{
2
"transcripts": [
3
{
4
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"service_sid": "GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
"sid": "GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
"date_created": "2010-08-31T20:36:28Z",
8
"date_updated": "2010-08-31T20:36:28Z",
9
"status": "queued",
10
"channel": {},
11
"data_logging": false,
12
"language_code": "en-US",
13
"media_start_time": null,
14
"duration": 0,
15
"customer_key": null,
16
"url": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
"redaction": true,
18
"links": {
19
"sentences": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Sentences",
20
"media": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media",
21
"operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OperatorResults"
22
}
23
}
24
],
25
"meta": {
26
"key": "transcripts",
27
"page": 0,
28
"page_size": 50,
29
"first_page_url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&ServiceSid=GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0",
30
"next_page_url": null,
31
"previous_page_url": null,
32
"url": "https://intelligence.twilio.com/v2/Transcripts?LanguageCode=en-US&SourceSid=REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&ServiceSid=GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&AfterDateCreated=2019-11-22T23%3A46%3A00Z&PageSize=50&Page=0"
33
}
34
}

Option 3: Find the Transcript SID via webhook event

option-3-find-the-transcript-sid-via-webhook-event page anchor

If the Voice Intelligence Service is set up to send a webhook event when a transcription completes, the webhook payload includes the transcript_sid key.

Step 2: Create a one-time token (OTT)

step-2-create-a-one-time-token-ott page anchor

The Transcription Viewer single-page application requires a short-lived, single-use token called a one-time token (OTT) to start a session. The OTT is used to obtain scoped Voice Intelligence API access so the single-page application can fetch an individual Transcript. The scoped API access is limited to one hour in a single user session. Token refresh isn't supported.

(error)

Danger

The request to create an OTT uses global Twilio Account credentials and requires a secure backend server. Don't expose Twilio Account credentials on the frontend.

Make a POST request to the following endpoint to request an OTT:

https://ai.twilio.com/v1/Tokens

The request must be authorized using HTTP Basic authentication, with the Twilio Account SID as the username and the Twilio Account Auth Token as the password.

OTT request body parameters

ott-request-body-parameters page anchor

The OTT request body supports the following parameters.

Parameter NameDescriptionTypeRequired?
ott_ttlA field that specifies a custom OTT expiry period in seconds, also known as time-to-live (TTL). If unspecified, the default is 60 seconds.integerNo
grantsAn array of grant objects. Only one grant is required for the Transcription Viewer single-page application.arrayYes
grants[].productA field that specifies the product functionality. Must be set to annotator for the Transcription Viewer single-page application.stringYes
grants[].service_sidThe SID of the Voice Intelligence Service associated with the Transcription.stringYes
grants[].transcript_sidThe SID of the Transcription.stringYes
grants[].metadataAn object containing metadata.objectNo
grants[].metadata.userIdA field to identify the user who is using the Transcription Viewer single-page application.stringNo
grants[].metadata.isDownloadButtonVisibleA field that specifies whether or not a download button is visible. If visible, the Transcription Viewer single-page application user can download the audio of a Transcript.booleanNo

If the OTT request is successful, the response includes the following properties:

Property NameDescriptionType
tokenThe value of the OTT.string
expirationThe date and time of the OTT's expiration, in ISO 8601(link takes you to an external page) format.string

Request a one-time token

request-a-one-time-token page anchor
1
fetch("https://ai.twilio.com/v1/Tokens", {
2
"headers": {
3
"authorization": `Basic ${btoa(ACCOUNT_SID + ":" + AUTH_TOKEN)}`,
4
"content-type": "application/json"
5
},
6
"body": JSON.stringify({
7
"grants": [{
8
"product": "annotator",
9
"service_sid": "GA00000000000000000000000000000000",
10
"transcript_sid": "GT00000000000000000000000000000000",
11
"metadata": {
12
"userId": "Jason Bourne",
13
"isDownloadButtonVisible": true
14
}
15
}]
16
}),
17
"method": "POST"
18
});

Request a one-time token with a 10-minute TTL

request-a-one-time-token-with-a-10-minute-ttl page anchor
1
fetch("https://ai.twilio.com/v1/Tokens", {
2
"headers": {
3
"authorization": `Basic ${btoa(ACCOUNT_SID + ":" + AUTH_TOKEN)}`,
4
"content-type": "application/json"
5
},
6
"body": JSON.stringify({
7
"ott_ttl": 600,
8
"grants": [{
9
"product": "annotator",
10
"service_sid": "GA00000000000000000000000000000000",
11
"transcript_sid": "GT00000000000000000000000000000000",
12
"metadata": {
13
"userId": "Jason Bourne",
14
"isDownloadButtonVisible": true
15
}
16
}]
17
}),
18
"method": "POST"
19
});

Step 3: Initialize and display the Transcription Viewer single-page application

step-3-initialize-and-display-the-transcription-viewer-single-page-application page anchor

Next, use the OTT as a URL query parameter to create a single-page application initialization URL using the latest Transcription Viewer single-page application build. This sample single-page application initialization URL assumes the OTT is stored in an environment variable named TOKEN:

https://assets.twilio.com/public_assets/annotator/latest/index.html?token=$TOKEN

How the single-page application initialization URL is used depends on how the single-page application is displayed. The single-page application can be displayed by either rendering it in a new window or embedding it into an existing web app.

Display option 1: Render the single-page application in a new window

display-option-1-render-the-single-page-application-in-a-new-window page anchor

To display the Transcription Viewer single-page application in its own browser window, redirect a window to the single-page application initialization URL:

1
app.get('/transcription-viewer/standalone', async (req, res) => {
2
const serviceSid = req.query.serviceSid;
3
const transcriptSid = req.query.transcriptSid;
4
5
const token = await client.getTranscriptionViewerToken(serviceSid, transcriptSid);
6
let url = `https://assets.twilio.com/public_assets/annotator/latest/index.html?token=${token}`;
7
return res.redirect(url);
8
});

Review the demo app(link takes you to an external page) for a sample implementation of the backend(link takes you to an external page) of a single-page application.

Display option 2: Embed the single-page application

display-option-2-embed-the-single-page-application page anchor

You can embed the Transcription Viewer single-page application into an existing web app using an HTML iframe. Add the single-page application initialization URL to an iframe tag as shown in the following example, noting that the $TOKEN variable must be generated from the backend:

<iframe src="https://assets.twilio.com/public_assets/annotator/latest/index.html?token=$TOKEN">

Review the demo app(link takes you to an external page) for sample implementations of the frontend(link takes you to an external page) and backend(link takes you to an external page) of an embedded single-page application.