On this page

Integrate the Transcription Viewer App

This guide will show you how to integrate Voice Intelligence Transcription Viewer applet into your own web app. It is intended to be used by developers and system integrators and assumes you have a working Voice Intelligence Service.

The Transcription Viewer is a web applet that your web app can retrieve, initialize, and present within its own UI. It allows a user to read a transcript of a recorded conversation that took place between a customer and one of your customer support agents.

You can present the Transcription Viewer as part of that UI or in a separate window that pops up when required. This guide shows 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.

Prerequisites

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.
A configured Voice Intelligence Service.
The SID of your Service.
Access to transcripts that you would like to view.

Instructions

Each time you wish to initialize and present the Transcription Viewer, you need to:

Fetch the SID of the transcript you would like to present.
Use your Account SID, Auth Token, and some metadata from the transcript to acquire a one-time token.
Pass the one-time token as a URL query parameter to initialize the Transcription Viewer.

Let's run through each of these steps now.

1. Fetch the transcript SID

There are a number of ways that you can acquire the SID of the transcript you'd like to view, so choose the one that best fits your application.

Option 1: Get a transcript for a particular call recording

If your application already has a Recording SID, you can look up the transcript SID by passing the Recording SID as a URL query parameter, SourceSid. This will narrow the search down to the transcript generated by that call recording.

Look under EXAMPLE JSON RESPONSE in the code column to the right. The returned data contains the key transcripts whose value is an array containing, in this case, one JSON object. The value of the object's sid key is the transcript SID you need. It starts with GT.

Get a transcript by Recording SID

1curl -X GET "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "transcripts": [
3    {
4      "status": "completed",
5      "sid": "GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6      "service_sid": "GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8      "redaction": false,
9      "data_logging": false,
10      "media_start_time": null,
11      "language_code": "en-US",
12      "customer_key": "",
13      "url": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14      "duration": 24,
15      "date_updated": "2024-03-15T09:57:23Z",
16      "date_created": "2024-03-15T09:55:33Z",
17      "channel": {
18        "media_properties": {
19            "source_sid": "REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
20            "media_url": null
21        },
22        "participants": [
23            {
24                "user_id": null,
25                "channel_participant": 1,
26                "media_participant_id": null,
27                "image_url": "",
28                "full_name": "Holly Rays",
29                "role": "customer",
30                "email": ""
31            },
32            {
33                "user_id": "akelley",
34                "channel_participant": 2,
35                "media_participant_id": null,
36                "image_url": "",
37                "full_name": "Adam Kelley",
38                "role": "agent",
39                "email": ""
40            }
41        ],
42        "type": "voice"
43      },
44      "links": {
45        "media": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media",
46        "sentences": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sentences",
47        "operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/OperatorResults"
48      }
49    }
50  ],
51  "meta": {
52    "key": "transcripts",
53    "page": 0,
54    "page_size": 50,
55    "first_page_url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0",
56    "next_page_url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=1",
57    "previous_page_url": null,
58    "url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0"
59  }
60}

Option 2: Get all transcripts

If you don't have a Recording SID, you can make the same request described above, but without the SourceSid query parameter. This will return all your transcriptions, so you need to be able to identify the one you want so you can extract its SID.

Again, under EXAMPLE JSON RESPONSE for the code sample, the returned data contains a transcripts key whose value is an array containing, in this case, a single JSON object (for a single transcription). The value of the object's sid key is the transcript SID you need, starting with GT.

Get a transcript by transcript SID

1curl -X GET "https://intelligence.twilio.com/v2/Transcripts?PageSize=20" \
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Output

1{
2  "transcripts": [
3    {
4      "status": "completed",
5      "sid": "GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6      "service_sid": "GAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7      "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
8      "redaction": false,
9      "data_logging": false,
10      "media_start_time": null,
11      "language_code": "en-US",
12      "customer_key": "",
13      "url": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
14      "duration": 24,
15      "date_updated": "2024-03-15T09:57:23Z",
16      "date_created": "2024-03-15T09:55:33Z",
17      "channel": {
18        "media_properties": {
19            "source_sid": "REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
20            "media_url": null
21        },
22        "participants": [
23            {
24                "user_id": null,
25                "channel_participant": 1,
26                "media_participant_id": null,
27                "image_url": "",
28                "full_name": "Holly Rays",
29                "role": "customer",
30                "email": ""
31            },
32            {
33                "user_id": "akelley",
34                "channel_participant": 2,
35                "media_participant_id": null,
36                "image_url": "",
37                "full_name": "Adam Kelley",
38                "role": "agent",
39                "email": ""
40            }
41        ],
42        "type": "voice"
43      },
44      "links": {
45        "media": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media",
46        "sentences": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Sentences",
47        "operator_results": "https://intelligence.twilio.com/v2/Transcripts/GTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/OperatorResults"
48      }
49    }
50  ],
51  "meta": {
52    "key": "transcripts",
53    "page": 0,
54    "page_size": 20,
55    "first_page_url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=20&Page=0",
56    "next_page_url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=20&Page=1",
57    "previous_page_url": null,
58    "url": "https://intelligence.twilio.com/v2/Transcripts?SourceSid=REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=20&Page=0"
59  }
60}

Option 3: Receive a notification when a transcription completes

To use this option, you'll need to set up the WebhookUrl parameter on your Service. You'll find the transcript_sid in the JSON data sent to your URL when a transcription completes.

2. Acquire a one-time token

Each Transcription Viewer session requires a new one-time token. This is a short-lived, single-use key that is used to authorize Transcription Viewer to access the transcript.

(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 one-time token by making a call to the endpoint:

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

You use your Twilio Account SID and Auth Token to authorize the request, which is submitted as JSON. The JSON includes a grants array containing an object. This object must include your service SID and the transcript SID as key-value pairs. Check out the examples below to see how the request body JSON is formatted.

In addition to service and transcript SIDs, you can include a user ID in the one-time token request's metadata section. This is optional. The user SID should be used to identify the user who will be opening the Transcription Viewer. This usage is shown in the examples below.

You can also choose to have Transcription Viewer display a button which, when clicked, allows the Agent to download the audio from which the transcript was made. To add this button, include an isDownloadButtonVisible key in the one-time token request's metadata section and set its value to true. Again, this 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. Please use annotator as its value.

(information)

Info

The one-time token is used internally by Transcription Viewer 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.

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  });

Output

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

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});

Output

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

3. Initialize the Transcription Viewer app

Once you've acquired a one-time token, pass it as a URL query parameter with your request for Transcription Viewer. The latest build of Transcription Viewer is available here:

https://assets.twilio.com/public_assets/annotator/latest/index.html

To request Transcription Viewer with the one-time token, just add a token parameter to the URL as follows:

https://assets.twilio.com/public_assets/annotator/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 Transcription Viewer in a standalone window

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

You might, for instance, choose to have your service redirect to this URL right after acquiring the token.

The entire flow might then be:

An Agent views a UI with a list of transcripts to view.
The Agent selects a transcript. This triggers a request to a backend service propagating the transcript SID and the service SID.
The backend service reads these SIDs from the request and uses locally-stored Twilio account credentials to generate a one-time token.
The backend service redirects the browser to the latest Transcription Viewer build with the token appended to the app's URL.

Example 2: Embed the Transcription Viewer inside your web app

The Transcription Viewer 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/annotator/latest/index.html?token=<YOUR_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:

An Agent views a UI with the list of transcripts to view.
The Agent selects a transcript. This triggers a request to a backend service propagating the transcript SID and the service SID.
The backend service reads these SIDs from the request and uses locally stored Twilio account credentials to generate a one-time token.
The backend service renders an HTML page that contains the iframe snippet above.

Integration FAQs

What is a one-time token?

The one-time token (OTT) is used internally by the Transcripiton Viewer 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. It's 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.