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 is available on GitHub for reference.

Prerequisites

Before beginning this guide, complete these steps:

Create a Twilio Account.
- Note the Account SID and Auth Token from the Console.
Create a Voice Intelligence Service.
- Note the SID of the Service from the API or the Console.
Have at least one Transcript associated with the Voice Intelligence Service.

Instructions

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

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

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 SID

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
19listTranscript();

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

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.

Fetch all Transcripts for an Account

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async 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
18listTranscript();

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

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)

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.

Request an OTT

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

The OTT request body supports the following parameters.

Parameter Name	Description	Type	Required?
`ott_ttl`	A field that specifies a custom OTT expiry period in seconds, also known as time-to-live (TTL). If unspecified, the default is `60` seconds.	`integer`	No
`grants`	An array of `grant` objects. Only one `grant` is required for the Transcription Viewer single-page application.	`array`	Yes
`grants[].product`	A field that specifies the product functionality. Must be set to `annotator` for the Transcription Viewer single-page application.	`string`	Yes
`grants[].service_sid`	The SID of the Voice Intelligence Service associated with the Transcription.	`string`	Yes
`grants[].transcript_sid`	The SID of the Transcription.	`string`	Yes
`grants[].metadata`	An object containing metadata.	`object`	No
`grants[].metadata.userId`	A field to identify the user who is using the Transcription Viewer single-page application.	`string`	No
`grants[].metadata.isDownloadButtonVisible`	A 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.	`boolean`	No

OTT Response properties

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

Property Name	Description	Type
`token`	The value of the OTT.	`string`
`expiration`	The date and time of the OTT's expiration, in ISO 8601 format.	`string`

Code samples

Request a one-time token

1fetch("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

1fetch("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

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

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

1app.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 for a sample implementation of the backend of a single-page application.

Display option 2: Embed the single-page application

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 for sample implementations of the frontend and backend of an embedded single-page application.