Skip to contentSkip to navigationSkip to topbar
On this page

Integrate the Transcripts App


This guide shows you how to integrate the Transcripts App facility into your web app. It is intended for developers and system integrators, and assumes that you have at least one working Voice Intelligence Service.

The Transcripts App is a web applet your web app can retrieve, initialize, and present within its own UI. It allows a user to search through transcripts of recorded conversations that took place between participants.

Voice Intelligence Transcripts App.

You can present the Transcripts App as part of your site's UI, or in its own window that pops up when it is required. We'll show you how to achieve both. In each case, your app requests the Transcription Viewer code by calling a specific URL and including an authorization token as a URL parameter.

A Transcripts App Integration Demo(link takes you to an external page) companion project that implements the topics discussed in this guide is available on GitHub(link takes you to an external page) for reference.


Prerequisites

prerequisites page anchor

To follow along with this guide, you should have the following elements set up and ready to use:

  • Twilio account credentials, specifically your Account SID and your Auth Token, which you can get from the Console .
  • Access to transcripts that you would like to search.

Each time you wish to search, the following operations need to take place:

  1. Your Account SID, Auth Token, and some metadata are used to acquire a one-time token.
  2. Pass the one-time token as a URL query parameter to initialize the Transcripts App.

Let's run through each of these steps now.

1. Acquire a one-time token

1-acquire-a-one-time-token page anchor

Each Transcript App session requires a new one-time token (OTT). This is a short-lived, single-use key that is used to authorize access to the transcript to be searched.

(error)

Danger

The request to acquire a token requires your global Twilio account credentials, so server-side usage requires a secure environment. Do not expose your Twilio account credentials to clients.

You request the OTT by making a call to this endpoint:

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

You use your Account SID and Auth Token to authorize the request, which is submitted as JSON. Check out the examples below to see how the request body JSON is formatted.

You can also include a default Service SID in the OTT request's metadata section if you wish. This is optional. It should be used to choose the selected service on the initial load. This usage is shown in the examples below.

You may also specify a custom token expiry period, called a TTL (Time To Live). The default value is one minute, and that's what's applied to the first of the following examples. The second example sets a TTL of 10 minutes (600 seconds) by adding an ott_ttl field to the request body.

With this data, you can acquire a one-time token. The basic structure of the request is shown below. The request JSON also includes a mandatory product field. This indicates the app you're requesting the token for — intelligence-discovery in this case.

(information)

Info

The one-time token is used internally by the Transcripts app to acquire a fully privileged and scoped access token for use during the lifetime of its session. It can be used once only. It's purpose is to avoid embedding a fully privileged access token in client-side code.

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": "intelligence-discovery"
9
}]
10
}),
11
"method": "POST"
12
});
Request a one-time token with a 10-minute TTL.Link to code sample: Request a one-time token with a 10-minute TTL.
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
});

Output

1
{
2
"token": "eyJ6a...",
3
"expiration": "2020-08-27T17:22:00Z"
4
}

2. Initialize the Transcripts App

2-initialize-the-transcripts-app page anchor

Once you've acquired a one-time token, pass it as a URL query parameter with your request for the Transcripts app itself. The latest Transcripts App build is available here:

https://assets.twilio.com/public_assets/intelligence-discovery/latest/index.html

So to request the app with the one-time token, just add a token parameter to the URL as follows:

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

This assumes your token is stored in an environment variable called TOKEN. You can now use this URL directly, or via an iframe in your web page HTML, as the following examples show.

Example 1: Use the Transcripts App in a standalone window

example-1-use-the-transcripts-app-in-a-standalone-window page anchor

If your app will present the Transcripts App functionality in its own browser window, open a new window and load its contents with the latest build as shown above. Make sure you include the one-time token as a URL query parameter.

The entire flow might then be:

  1. The frontend issues a request to a backend service.
  2. The backend service uses locally stored Twilio account credentials to generate a one-time token.
  3. The backend service redirects the browser to the latest Transcription Viewer build with the token appended to the app's URL.

Check out the standalone endpoint in the Transcripts App Integration Demo(link takes you to an external page) for a sample implementation of this flow(link takes you to an external page).

Example 2: Embed Transcrips App inside your web app

example-2-embed-transcrips-app-inside-your-web-app page anchor

The Transcripts App can be embedded in an HTML iframe. To do so, add the URL and appended token to the iframe markup like this:

<iframe src="https://assets.twilio.com/public_assets/intelligence-discovery/latest/index.html?token={THE_ONE_TIME_TOKEN}">

To achieve this, your server will likely need to retrieve and then dynamically embed the token into the HTML.

The entire flow might then be:

  1. The frontend issues a request to a backend service.
  2. The backend service uses locally stored Twilio account credentials to generate a one-time token.
  3. The backend service renders an HTML page that contains the iframe snippet above.

Take a look at the embedded endpoint Transcripts Integration Demo(link takes you to an external page) for a sample implementation of this flow(link takes you to an external page).

(warning)

Warning

If the Transcripts App is empty you might need to change the Service name selection or Date range filters.

Only the last 90 days transcriptions are available in the Transcriptions App to search and view.

If you still don't see any transcription, please check your Service configuration or create new Transcripts.


What is a one-time token?

The one-time token (OTT) is used internally by the Transcripts app to acquire a fully privileged access token for use during the lifetime of a search operation. It is short lived — approximately one minute — and can be used once only. Its purpose is to avoid embedding a fully privileged access token in client-side code.

How is token refresh handled?

Token refresh is not supported during preview. The one-time token is exchanged for a token with a time to live of one hour.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.