Skip to contentSkip to navigationSkip to topbar
On this page

Transcripts Integration Guide


This guide explains how to integrate and use the Transcripts single-page application in an existing web application. The Transcripts single-page application allows users to filter and view summary details of Voice Intelligence Transcripts of recorded conversations created in the past 90 days. Optionally, you can add the ability to view individual Transcripts in detail.

(information)

Info

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

The Voice Intelligence Transcripts single-page app UI. A filterable table includes the option to view each 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.

Search terms entered in the Phrases search box are linked with the OR operator. For example, searching for the phrase macaroni salad will match Transcripts that contain macaroni OR salad.

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 you begin, complete these steps:


The following steps explain how to integrate the Transcripts single-page application into a web app. The integration can be completed before a Voice Intelligence Service with associated Transcriptions is created, although the single-page application will render with an error.

To view a specific Transcript, you need to link the single-page application to the Transcription Viewer single-page application. This is an optional step, see [Step 3](#step-3-optional-link-with-the-transcription-viewer-single-page application) for more information.

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

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

The Transcripts 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 Transcripts to populate the table. 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

request-an-ott page anchor

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

POST 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. Note that some parameters are only required if linking with the Transcription Viewer single-page application in [Step 3](#step-3-optional-link-with-the-transcription-viewer-single-page application).

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, containing the properties product and metadata. Only one grant is required for the Transcripts single-page application.arrayYes
grants[].productA field that specifies the product functionality. Must be set to intelligence-discovery for the Transcripts single-page application.stringYes
grants[].metadataAn object containing metadata.objectNo
grants[].metadata.defaultServiceSids[]An array of Service SID strings. If provided, the single-page application only fetches Transcripts associated with the given Service SIDs. If unspecified, the single-page application fetches all Transcripts associated with the given Account.arrayNo
grants[].metadata.viewLinksAn object containing a conversationViewLink object.objectYes, if linking with the Transcription Viewer single-page application.
grants[].metadata.viewLinks.conversationViewLinkAn object containing the target and href properties for the Transcript view link.objectYes, if linking with the Transcription Viewer single-page application.
grants[].metadata.viewLinks.conversationViewLink.targetThe target of the Transcript view link. Typically set to _top to view the Transcript in the same window or _blank in a new window.stringYes, if linking with the Transcription Viewer single-page application.
grants[].metadata.viewLinks.conversationViewLink.hrefA static URL with placeholders used to generate links to view specific Transcripts. See href parameter for more details.stringYes, if linking with the Transcription Viewer single-page application.
href parameter
href-parameter page anchor

The value of the href parameter depends on if the Account has any Voice Intelligence Services with PII redaction enabled.

  • If PII redaction isn't enabled on any of the Account's Voice Intelligence Services, set href to:
http://localhost:8080/annotator/standalone?serviceSid=:serviceSid&transcriptSid=:transcriptSid
  • If PII redaction is enabled on one or more of the Account's Voice Intelligence Services, set href to:
http://localhost:8080/annotator/standalone?serviceSid=:serviceSid&transcriptSid=:transcriptSid&sensitive=:sensitive

The placeholder values for href don't need to be replaced in the OTT request. The placeholders are automatically replaced by the single-page application with the actual values for the Service SID, Transcript SID, and sensitive flag.

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 an OTT with the default 60 second TTL

request-an-ott-with-the-default-60-second-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
"grants": [{
8
"product": "intelligence-discovery"
9
}]
10
}),
11
"method": "POST"
12
});

Request an OTT with optional parameters

request-an-ott-with-optional-parameters 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": "intelligence-discovery",
10
"metadata": {
11
"defaultServiceSids": ["GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
12
}
13
}]
14
}),
15
"method": "POST"
16
});

Request an OTT if linking to the Transcription Viewer single-page application

request-an-ott-if-linking-to-the-transcription-viewer-single-page-application 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": "intelligence-discovery",
9
"metadata": {
10
"viewLinks": {
11
"conversationViewLink": {
12
"target": "_top",
13
"href": "http://localhost:8080/annotator/standalone?serviceSid=:serviceSid&transcriptSid=:transcriptSid"
14
}
15
}
16
}
17
}]
18
}),
19
"method": "POST"
20
});

Step 2: Initialize and display the Transcripts single-page application

step-2-initialize-and-display-the-transcripts-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 Transcripts single-page application build. This sample single-page application initialization URL assumes the OTT is stored in an environment variable named TRANSCRIPTS_TOKEN:

https://assets.twilio.com/public_assets/intelligence-discovery/latest/index.html?token=$TRANSCRIPTS_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 embedding it into an existing web app or rendering it in a new window.

Display option 1: Embed the single-page application

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

The Transcripts single-page application can be embedded into an existing web app using an HTML iframe. Add the single-page application initialization URL to an iframe tag as seen below, noting that the $TOKEN variable must be generated from the backend:

<iframe src="https://assets.twilio.com/public_assets/intelligence-discovery/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.

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

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

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

1
app.get('/transcripts/standalone', async (req, res) => {
2
const token = await client.getTranscriptsToken();
3
let url = `${transcriptsAssetUrl}?token=${token}`;
4
return res.redirect(url);
5
});

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.

Add a new endpoint to handle the Transcript Viewer single-page application requests with the path /transcript-viewer/standalone. This endpoint is called whenever a user selects a View link for a Transcript in the Transcripts Viewer single-page application. The endpoint should receive a Service SID and Transcript SID as query parameters, request a Transcription Viewer single-page application OTT, and return a Transcription Viewer single-page application initialization URL.

Review the demo app(link takes you to an external page) for a sample implementation of the Transcript Viewer endpoint(link takes you to an external page).

Request a Transcription Viewer OTT
request-a-transcription-viewer-ott page anchor

The Transcription Viewer OTT is used to obtain scoped Voice Intelligence API access so the Transcription Viewer single-page application can fetch an individual Transcript. A new Transcription Viewer OTT must be created for each Transcript that the user wants to view.

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 being requested by the single-page application. 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

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

Request an additional OTT for the Transcription Viewer single-page application

request-an-additional-ott-for-the-transcription-viewer-single-page-application page anchor
1
var serviceSid = "GAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
2
var transcriptSid = "GTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
3
4
fetch(
5
'https://ai.twilio.com/v1/Tokens',
6
{
7
method: 'POST',
8
headers: {
9
Authorization: `Basic ${twilioEncodedCreds}`,
10
'Content-Type': 'application/json'
11
},
12
body: JSON.stringify({
13
grants: [{
14
product: 'annotator',
15
service_sid: serviceSid,
16
transcript_sid: transcriptSid
17
}]
18
})
19
}
20
);
Create a Transcription Viewer single-page application initialization URL
create-a-transcription-viewer-single-page-application-initialization-url page anchor

To create the Transcription Viewer single-page application initialization URL, use the latest Transcription Viewer single-page application build and the OTT as a query parameter. The sample initialization URL below assumes the OTT is stored in an environment variable named TRANSCRIPTION_VIEWER_TOKEN:

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

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

1
app.get('/transcript-viewer/standalone', async (req, res) => {
2
const serviceSid = req.query.serviceSid;
3
const transcriptSid = req.query.transcriptSid;
4
if (serviceSid && transcriptSid) {
5
const token = await client.getTranscriptViewerToken(serviceSid, transcriptSid);
6
const url = `${transcriptViewerInitializationUrl}?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 Transcription Viewer endpoint(link takes you to an external page).