Transcript search
/api/v2/speechandtextanalytics/transcripts/search
The transcript search endpoint is used to query individual transcripts or transcripts metadata grouped by conversation.
Individual Transcripts
Use the transcripts type to search content and metadata fields on individual transcripts. Content is only searchable for 60 days.
Transcripts Metadata Grouped By Conversation
Use the transcripts_metadata type to search metadata fields on transcripts grouped by conversation. A maximum of 100 transcripts are searchable per conversation and the number of transcripts returned can be limited further by using the maxTranscriptsPerConversation query parameter. The totalTranscripts field on each item in the results shows the total searchable transcripts for that conversation. Transcripts metadata is searchable for 18 months.
Pagination is only supported through the first 1,000 results. Note that the pagination limit for searching transcripts is more restrictive than most other search resources listed on our search limits documentation page.
Most Important Searchable Fields
Searchable Field | Field type | Description |
transcript.content | String | The text content of the transcript |
language | String | The transcript language |
mediaType | String | The mediaType associated with the transcript |
divisionId | String | Search only against specific divisionID(s). If divisionID criteria is not included in your query, then the search will be made against all divisionIDs for which the user has view permissions |
Any valid language code supported by Genesys Cloud can be passed for the language criteria. These currently include, but may not be limited to:
- de-de (German)
- en-au (English Australia)
- en-gb (English United Kingdom)
- en-in (English India)
- en-us (English US)
- en-za (English South Africa)
- es-es (Spanish Europe)
- es-us (Spanish US)
- fr-ca (French Canada)
- fr-fr (French)
- it-it (Italian)
- pt-br (Portuguese Brazil)
- unknown (Unknown)
Supported query types for searching against the transcript.content field include:
- EXACT
- Use EXACT to search for up to 50 single words that match exactly the way they appear in the text. Ordering of the words in the text does not matter.
- EXACT_PHRASE
- Use EXACT_PHRASE to search for a sequence of words in an exact ordering. The words need to match exactly the way they appear in the text.
- PHRASE
- Use PHRASE to search for a sequence of words in an exact ordering. The words do not need to match exactly the way they appear in the text. This query type will be more flexible in accounting for different word variations and search term stemming.
Current supported values for mediaType field include:
- call
- chat
- message
Fetching conversation details
By including the conversationId field in the returnFields array in the request body, the conversation IDs associated with each transcript will be returned in the response. This would allow you to make an additional API call to one of the conversation API resources, such as /api/v2/conversations/{conversationId} to fetch conversation details using the IDs returned in the response.
Fetching transcript details
By including both the conversationId and communicationId fields in the returnFields array in the request body, the communication and conversation IDs will be returned in the response. This would allow you to make an additional API call to one of the speech and text analytics API resources, such as /api/v2/speechandtextanalytics/conversations/{conversationId}/communications/{communicationId}/transcripturl to fetch transcript details using the IDs returned in the response.
Example: Search English transcripts using EXACT
The following request searches for English transcripts with the exact words subscription and cancel found anywhere in the text.
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT",
"fields": [
"transcript.content"
],
"values": [
"subscription",
"cancel"
]
}
]
}{
"total": 7,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"_type": "transcripts"
},
{
"transcriptId": "8efed22c-d115-43a6-b0a4-4a30f11cd719",
"conversationId": "8c40e75b-c15b-4822-b5db-ea97a95fe1ab",
"_type": "transcripts"
},
{
"transcriptId": "6b427509-30a7-4915-b612-f07960030cae",
"conversationId": "7dad4498-fa5d-4ead-a0a6-791572f7c9c6",
"_type": "transcripts"
},
{
"transcriptId": "b274015c-9ce1-4a5b-b7f0-c11d8c82149e",
"conversationId": "fc3f3b31-0790-480f-b9e1-e41100fe3dfe",
"_type": "transcripts"
},
{
"transcriptId": "22dcef49-5dbe-4f7b-a4e3-42ae55de3979",
"conversationId": "19df88e7-507d-470f-bc89-139e08908660",
"_type": "transcripts"
},
{
"transcriptId": "e6711d0d-c8dc-4726-90c0-820382330ba2",
"conversationId": "d4e0484a-5bfc-42f7-83ea-f91e58f37321",
"_type": "transcripts"
}
]
}Example: Search English transcripts using EXACT_PHRASE
The following request searches for English transcripts with the exact sequence of words my subscription will be cancelled tomorrow morning in the text.
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId",
"communicationId"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT_PHRASE",
"fields": [
"transcript.content"
],
"value": "my subscription will be cancelled tomorrow morning"
}
]
}{
"total": 1,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"communicationId": "986922c6-c778-4a32-8055-d5ff45c186d3",
"_type": "transcripts"
}
]
}Example: Search Spanish transcripts in a specific division and date range using PHRASE query type, return conversationIds in response
The following request uses the PHRASE query type to search for Spanish transcripts with the text mi suscripción but not the text cancelación within a certain date range. The query will return the conversationId and communicationId in the response. Note that you are able to pass in an epoch date format for the date range criteria.
{
"types": [
"transcripts"
],
"returnFields": [
"conversationId",
"communicationId"
],
"query": [
{
"fields": [
"divisionId"
],
"type": "EXACT",
"value": "73155fa8-4db0-41c1-8d54-5f0660cfd521"
},
{
"type": "EXACT",
"fields": [
"language"
],
"value": "es-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "PHRASE",
"fields": [
"transcript.content"
],
"value": "mi suscripción"
},
{
"type": "PHRASE",
"fields": [
"transcript.content"
],
"value": "cancelación",
"operator": "NOT"
},
{
"type": "DATE_RANGE",
"fields": [
"conversationStartTime"
],
"startValue": 384066000000,
"endValue": 386744400000
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "cc014906-459e-4e55-a2c9-50f85d3271fe",
"communicationId": "986922c6-c778-4a32-8055-d5ff45c186d3",
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "20518039-7484-4cb0-93d8-c7b29fe9669c",
"communicationId": "a9ff42db-c6d4-4ab2-9ae5-e0338c634a71",
"_type": "transcripts"
}
]
}When crafting complex queries, keep in mind that there are specific query limits you'll need to consider, such as max number of criteria. Refer to our search limits documentation for guidance.
Aggregations
Current supported fields for performing TERM aggregation queries include:
- language
This can be useful to see a count of the transcript languages included in the results.
Example: Search transcripts from a specific division with an aggregation on the language field
The following request searches for transcripts within a specific division and asks for aggregation results on the language field.
{
"types": [
"transcripts"
],
"returnFields": [
"conversationId"
],
"query": [
{
"fields": [
"divisionId"
],
"type": "EXACT",
"value": "73155fa8-4db0-41c1-8d54-5f0660cfd521"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
}
],
"aggregations": [
{
"name": "lang",
"field": "language",
"type": "TERM",
"size": 10
}
]
}{
"total": 5,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "8efed22c-d115-43a6-b0a4-4a30f11cd719",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"_type": "transcripts"
},
{
"transcriptId": "6b427509-30a7-4915-b612-f07960030cae",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"_type": "transcripts"
},
{
"transcriptId": "b274015c-9ce1-4a5b-b7f0-c11d8c82149e",
"conversationId": "60b7e98d-7aa1-4424-a3ca-df40ce089e39",
"_type": "transcripts"
},
{
"transcriptId": "22dcef49-5dbe-4f7b-a4e3-42ae55de3979",
"conversationId": "53df75a1-649f-43df-859b-bd9bed33e924",
"_type": "transcripts"
},
{
"transcriptId": "e6711d0d-c8dc-4726-90c0-820382330ba2",
"conversationId": "cddca58d-7d56-4496-8c6f-a636ee6415e7",
"_type": "transcripts"
}
],
"aggregations": {
"lang": [
{
"key": "en-us",
"count": 3
},
{
"key": "es-us",
"count": 2
}
]
}
}Additional Searchable Fields
Searchable Field | Field type | Description |
communicationId | String | The communicationId associated with the transcript |
conversationId | String | The conversationId associated with the transcript |
conversationSentimentScore | Number | The sentiment score metric associated with the conversation |
conversationSentimentTrend | Number | The sentiment trend metric associated with the conversation |
participants.initialDirection | String | The initialDirection of a participant in the conversation |
participants.participantPurpose | String | The participantPurpose of a participant in the conversation |
participants.queueId | String | The queueId of a participant in the conversation |
participants.userId | String | The participantPurpose of a participant in the conversation |
topics.name | String | The name of the detected topic on the transcript |
topics.id | String | The ID of the detected topic on the transcript |
topics.participant | String | The participant ID the detected topic was for |
transcriptId | String | The id of the transcript |
Supported query types for searching against the conversationSentimentScore and conversationSentimentTrend fields include:
- GREATER_THAN
- find transcripts with conversation sentiment metrics above a value
- LESS_THAN
- find transcripts with conversation sentiment metrics below a value
- RANGE
- find transcripts with conversation sentiment metrics within a range of values
Example: Search English transcripts from a specific user, in a specific queue, and within a specific date range
The following request searches for English transcripts from a specific user in a specific queue that match the text accept the terms and conditions. Note that you are able to pass in a string date format for the date range criteria.
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT",
"fields": [
"participants.queueId"
],
"value": "5ecfd7d3-60c4-4f17-bd19-0343b5be77c0"
},
{
"type": "EXACT",
"fields": [
"participants.userId"
],
"value": "e6e3a132-f290-4d3b-b8d7-4dff62a44490"
},
{
"type": "PHRASE_EXACT",
"fields": [
"transcript.content"
],
"value": "accept the terms and conditions"
},
{
"type": "DATE_RANGE",
"fields": [
"conversationStartTime"
],
"startValue": "2020-04-15T00:00:00.000Z",
"endValue": "2020-04-16T00:00:00.000Z",
"dateFormat": "yyyy-MM-dd'T'HH:mm:ss.SSSX"
}
]
}{
"total": 3,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"_type": "transcripts"
},
{
"transcriptId": "8efed22c-d115-43a6-b0a4-4a30f11cd719",
"conversationId": "cddca58d-7d56-4496-8c6f-a636ee6415e7",
"_type": "transcripts"
}
]
}Example: Search English transcripts with sentiment score between 0.1 and 0.5
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "RANGE",
"fields": [
"conversationSentimentScore"
],
"startValue": 0.1,
"endValue": 0.5
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"conversationSentimentScore": 0.38,
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"conversationSentimentScore": 0.21,
"_type": "transcripts"
}
]
}Example: Search English transcripts with sentiment trend less than 0.3
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "LESS_THAN",
"fields": [
"conversationSentimentTrend"
],
"value": 0.3
}
]
}{
"total": 1,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"conversationSentimentTrend": 0.23,
"_type": "transcripts"
}
]
}Example: Search English transcripts with specific detected topic
The following request searches for English transcripts with a specific detected topic.
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId",
"topics"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT",
"fields": [
"topics.name"
],
"value": "shipping"
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"topics": [{
"id": "b868cb16-3627-45d5-0000-5f16c43922ca",
"name": "shipping",
"participant: "b868cb16-3627-45d5-1111-5f16c43922ca"
}],
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"topics": [{
"id": "b868cb16-3627-45d5-0000-5f16c43922ca",
"name": "shipping",
"participant: "b868cb16-3627-45d5-1111-5f16c43922ca"
}, {
"id": "00000000-3627-45d5-0000-5f16c43922ca",
"name": "return",
"participant: "11111111-3627-45d5-1111-5f16c43922ca"
}]
"_type": "transcripts"
}
]
}Example: Search English transcripts with at least one detected topic from a list of topics.
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"returnFields": [
"conversationId",
"topics"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT",
"fields": [
"topics.name"
],
"values": [
"shipping",
"defect"
]
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts"
],
"results": [
{
"transcriptId": "b868cb16-3627-45d5-840d-5f16c43922ca",
"conversationId": "dff7eda2-1455-4f09-9828-0a5b62bcff27",
"topics": [{
"id": "b868cb16-3627-45d5-0000-5f16c43922ca",
"name": "shipping",
"participant: "b868cb16-3627-45d5-1111-5f16c43922ca"
}],
"_type": "transcripts"
},
{
"transcriptId": "1711037b-4283-4cfe-8ac4-10d7c2ac665f",
"conversationId": "1200f9b3-4ac5-461c-866b-ce377a285927",
"topics": [{
"id": "b868cb16-3627-45d5-0000-5f16c43922ca",
"name": "defect",
"participant: "b868cb16-3627-45d5-1111-5f16c43922ca"
}, {
"id": "00000000-3627-45d5-0000-5f16c43922ca",
"name": "unhappy",
"participant: "11111111-3627-45d5-1111-5f16c43922ca"
}]
"_type": "transcripts"
}
]
}Example: Search transcripts metadata by language, media type and topic name
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts_metadata"
],
"returnFields": [
"conversation.id",
"topics.name"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "en-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "EXACT",
"fields": [
"topics.name"
],
"values": [
"shipping",
"defect"
]
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts_metadata"
],
"results": [{
"transcripts": [
{
"topics": [
{
"name": "shipping"
}
],
"transcriptId": "6a3af0d5-acf2-462a-8939-1d90da2b3156"
},
{
"transcriptId": "00000000-acf2-462a-8939-1d90da2b3156"
}
],
"conversation": {
"id": "0902fb24-0641-46d8-8c70-4de373bca026"
},
"totalTranscripts": 2
"_type": "transcripts_metadata"
},
{
"transcripts": [
{
"topics": [
{
"name": "defect"
}
],
"transcriptId": "3850d091-2467-4b21-adf0-d8ca312ea533"
}
],
"conversation": {
"id": "f4736a12-a406-4cd0-ba34-990357e7839a"
},
"totalTranscripts": 1
"_type": "transcripts_metadata"
}]
}Example: Search transcripts metadata by conversation sentiment score and limit the number of transcripts returned per conversation
{
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts_metadata"
],
"returnFields": [
"conversation.id",
"conversation.sentiment"
],
"query": [
{
"type": "RANGE",
"fields": [
"conversation.sentiment.score"
],
"startValue": 50,
"endValue": 100
}
]
}{
"total": 2,
"pageCount": 1,
"pageSize": 25,
"pageNumber": 1,
"types": [
"transcripts_metadata"
],
"results": [{
"transcripts": [
{
"transcriptId": "6a3af0d5-acf2-462a-8939-1d90da2b3156"
}
],
"conversation": {
"sentiment": {
"score": 76.8,
"trend": 80.1
},
"id": "0902fb24-0641-46d8-8c70-4de373bca026"
},
"totalTranscripts": 4
"_type": "transcripts_metadata"
},
{
"transcripts": [
{
"transcriptId": "3850d091-2467-4b21-adf0-d8ca312ea533"
}
],
"conversation": {
"sentiment": {
"score": 52.3,
"trend": 61.0
},
"id": "f4736a12-a406-4cd0-ba34-990357e7839a"
},
"totalTranscripts": 3
"_type": "transcripts_metadata"
}]
}/api/v2/analytics/conversations/transcripts/query
There is another endpoint which accepts the same request body as /api/v2/speechandtextanalytics/transcripts/search and returns conversation details in the response instead of transcript details. However, it is more ideal to use /api/v2/speechandtextanalytics/transcripts/search to return only the conversationId in the results and then fetch the conversation details with the conversationId in a separate API call.
- return conversation details in response
- returnFields property is not supported. All conversation fields will be returned in the response.
- pagination and sorting is not supported
- returns a limit of 25 conversations
Example: Search Spanish transcripts, return conversation details in response
The following request searches for Spanish transcripts matching suscripción but not cancelación. There are 4 results in the response. Note that no pagination details are included in the response because this endpoint does not support pagination.
{
"types": [
"transcripts"
],
"query": [
{
"type": "EXACT",
"fields": [
"language"
],
"value": "es-us"
},
{
"type": "EXACT",
"fields": [
"mediaType"
],
"value": "call"
},
{
"type": "PHRASE",
"fields": [
"transcript.content"
],
"value": "suscripción"
},
{
"type": "PHRASE",
"fields": [
"transcript.content"
],
"value": "cancelación",
"operator": "NOT"
}
]
}{
"conversations": [
{<conversation detail object>},
{<conversation detail object>},
{<conversation detail object>},
{<conversation detail object>}
]
}