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.
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.
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.
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.
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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listTranscript() {11const transcripts = await client.intelligence.v2.transcripts.list({12sourceSid: "REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",13limit: 20,14});1516transcripts.forEach((t) => console.log(t.accountSid));17}1819listTranscript();
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}
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/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listTranscript() {11const transcripts = await client.intelligence.v2.transcripts.list({12limit: 20,13});1415transcripts.forEach((t) => console.log(t.accountSid));16}1718listTranscript();
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}
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.
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.
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.
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 |
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 |
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": true14}15}]16}),17"method": "POST"18});
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": true15}16}]17}),18"method": "POST"19});
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.
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) => {2const serviceSid = req.query.serviceSid;3const transcriptSid = req.query.transcriptSid;45const token = await client.getTranscriptionViewerToken(serviceSid, transcriptSid);6let url = `https://assets.twilio.com/public_assets/annotator/latest/index.html?token=${token}`;7return res.redirect(url);8});
Review the demo app for a sample implementation of the backend of a 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.