StartCallAnalyticsStreamTranscription

Starts a bidirectional HTTP/2 or WebSocket stream where audio is streamed to Amazon Transcribe and the transcription results are streamed to your application. Use this operation for Call Analytics transcriptions.

The following parameters are required:

• language-code

• media-encoding

• sample-rate

For more information on streaming with Amazon Transcribe, see Transcribing streaming audio.

Request Syntax

POST /call-analytics-stream-transcription HTTP/1.1
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-vocabulary-filter-name: VocabularyFilterName
x-amzn-transcribe-vocabulary-filter-method: VocabularyFilterMethod
x-amzn-transcribe-language-model-name: LanguageModelName
x-amzn-transcribe-enable-partial-results-stabilization: EnablePartialResultsStabilization
x-amzn-transcribe-partial-results-stability: PartialResultsStability
x-amzn-transcribe-content-identification-type: ContentIdentificationType
x-amzn-transcribe-content-redaction-type: ContentRedactionType
x-amzn-transcribe-pii-entity-types: PiiEntityTypes
Content-type: application/json

{
   "AudioEvent": { 
      "AudioChunk": blob
   },
   "ConfigurationEvent": { 
      "ChannelDefinitions": [ 
         { 
            "ChannelId": number,
            "ParticipantRole": "string"
         }
      ],
      "PostCallAnalyticsSettings": { 
         "ContentRedactionOutput": "string",
         "DataAccessRoleArn": "string",
         "OutputEncryptionKMSKeyId": "string",
         "OutputLocation": "string"
      }
   }
}

URI Request Parameters

The request uses the following URI parameters.

ContentIdentificationType

Labels all personally identifiable information (PII) identified in your transcript.

Content identification is performed at the segment level; PII specified in PiiEntityTypes is flagged upon complete transcription of an audio segment. If you don't include PiiEntityTypes in your request, all PII is identified.

You can’t set ContentIdentificationType and ContentRedactionType in the same request. If you set both, your request returns a BadRequestException.

For more information, see Redacting or identifying personally identifiable information.

Valid Values: PII

ContentRedactionType

Redacts all personally identifiable information (PII) identified in your transcript.

Content redaction is performed at the segment level; PII specified in PiiEntityTypes is redacted upon complete transcription of an audio segment. If you don't include PiiEntityTypes in your request, all PII is redacted.

You can’t set ContentRedactionType and ContentIdentificationType in the same request. If you set both, your request returns a BadRequestException.

For more information, see Redacting or identifying personally identifiable information.

Valid Values: PII

EnablePartialResultsStabilization

Enables partial result stabilization for your transcription. Partial result stabilization can reduce latency in your output, but may impact accuracy. For more information, see Partial-result stabilization.

LanguageCode

Specify the language code that represents the language spoken in your audio.

For a list of languages supported with real-time Call Analytics, refer to the Supported languages table.

Valid Values: en-US | en-GB | es-US | fr-CA | fr-FR | en-AU | it-IT | de-DE | pt-BR

Required: Yes

LanguageModelName

Specify the name of the custom language model that you want to use when processing your transcription. Note that language model names are case sensitive.

The language of the specified language model must match the language code you specify in your transcription request. If the languages don't match, the custom language model isn't applied. There are no errors or warnings associated with a language mismatch.

For more information, see Custom language models.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

MediaEncoding

Specify the encoding of your input audio. Supported formats are:

• FLAC

• OPUS-encoded audio in an Ogg container

• PCM (only signed 16-bit little-endian audio formats, which does not include WAV)

For more information, see Media formats.

Valid Values: pcm | ogg-opus | flac

Required: Yes

MediaSampleRateHertz

The sample rate of the input audio (in hertz). Low-quality audio, such as telephone audio, is typically around 8,000 Hz. High-quality audio typically ranges from 16,000 Hz to 48,000 Hz. Note that the sample rate you specify must match that of your audio.

Valid Range: Minimum value of 8000. Maximum value of 48000.

Required: Yes

PartialResultsStability

Specify the level of stability to use when you enable partial results stabilization (EnablePartialResultsStabilization).

Low stability provides the highest accuracy. High stability transcribes faster, but with slightly lower accuracy.

For more information, see Partial-result stabilization.

Valid Values: high | medium | low

PiiEntityTypes

Specify which types of personally identifiable information (PII) you want to redact in your transcript. You can include as many types as you'd like, or you can select ALL.

Values must be comma-separated and can include: ADDRESS, BANK_ACCOUNT_NUMBER, BANK_ROUTING, CREDIT_DEBIT_CVV, CREDIT_DEBIT_EXPIRY, CREDIT_DEBIT_NUMBER, EMAIL, NAME, PHONE, PIN, SSN, or ALL.

Note that if you include PiiEntityTypes in your request, you must also include ContentIdentificationType or ContentRedactionType.

If you include ContentRedactionType or ContentIdentificationType in your request, but do not include PiiEntityTypes, all PII is redacted or identified.

Length Constraints: Minimum length of 1. Maximum length of 300.

Pattern: ^[A-Z_, ]+

SessionId

Specify a name for your Call Analytics transcription session. If you don't include this parameter in your request, Amazon Transcribe generates an ID and returns it in the response.

Length Constraints: Fixed length of 36.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

VocabularyFilterMethod

Specify how you want your vocabulary filter applied to your transcript.

To replace words with ***, choose mask.

To delete words, choose remove.

To flag words without changing them, choose tag.

Valid Values: remove | mask | tag

VocabularyFilterName

Specify the name of the custom vocabulary filter that you want to use when processing your transcription. Note that vocabulary filter names are case sensitive.

If the language of the specified custom vocabulary filter doesn't match the language identified in your media, the vocabulary filter is not applied to your transcription.

For more information, see Using vocabulary filtering with unwanted words.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

VocabularyName

Specify the name of the custom vocabulary that you want to use when processing your transcription. Note that vocabulary names are case sensitive.

If the language of the specified custom vocabulary doesn't match the language identified in your media, the custom vocabulary is not applied to your transcription.

For more information, see Custom vocabularies.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Request Body

The request accepts the following data in JSON format.

AudioEvent

A blob of audio from your application. Your audio stream consists of one or more audio events.

For more information, see Event stream encoding.

Type: AudioEvent object

Required: No

ConfigurationEvent

Contains audio channel definitions and post-call analytics settings.

Type: ConfigurationEvent object

Required: No

Response Syntax

HTTP/1.1 200
x-amzn-request-id: RequestId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-vocabulary-filter-name: VocabularyFilterName
x-amzn-transcribe-vocabulary-filter-method: VocabularyFilterMethod
x-amzn-transcribe-language-model-name: LanguageModelName
x-amzn-transcribe-enable-partial-results-stabilization: EnablePartialResultsStabilization
x-amzn-transcribe-partial-results-stability: PartialResultsStability
x-amzn-transcribe-content-identification-type: ContentIdentificationType
x-amzn-transcribe-content-redaction-type: ContentRedactionType
x-amzn-transcribe-pii-entity-types: PiiEntityTypes
Content-type: application/json

{
   "BadRequestException": { 
   },
   "CategoryEvent": { 
      "MatchedCategories": [ "string" ],
      "MatchedDetails": { 
         "string" : { 
            "TimestampRanges": [ 
               { 
                  "BeginOffsetMillis": number,
                  "EndOffsetMillis": number
               }
            ]
         }
      }
   },
   "ConflictException": { 
   },
   "InternalFailureException": { 
   },
   "LimitExceededException": { 
   },
   "ServiceUnavailableException": { 
   },
   "UtteranceEvent": { 
      "BeginOffsetMillis": number,
      "EndOffsetMillis": number,
      "Entities": [ 
         { 
            "BeginOffsetMillis": number,
            "Category": "string",
            "Confidence": number,
            "Content": "string",
            "EndOffsetMillis": number,
            "Type": "string"
         }
      ],
      "IsPartial": boolean,
      "IssuesDetected": [ 
         { 
            "CharacterOffsets": { 
               "Begin": number,
               "End": number
            }
         }
      ],
      "Items": [ 
         { 
            "BeginOffsetMillis": number,
            "Confidence": number,
            "Content": "string",
            "EndOffsetMillis": number,
            "Stable": boolean,
            "Type": "string",
            "VocabularyFilterMatch": boolean
         }
      ],
      "ParticipantRole": "string",
      "Sentiment": "string",
      "Transcript": "string",
      "UtteranceId": "string"
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

ContentIdentificationType

Shows whether content identification was enabled for your Call Analytics transcription.

Valid Values: PII

ContentRedactionType

Shows whether content redaction was enabled for your Call Analytics transcription.

Valid Values: PII

EnablePartialResultsStabilization

Shows whether partial results stabilization was enabled for your Call Analytics transcription.

LanguageCode

Provides the language code that you specified in your Call Analytics request.

Valid Values: en-US | en-GB | es-US | fr-CA | fr-FR | en-AU | it-IT | de-DE | pt-BR

LanguageModelName

Provides the name of the custom language model that you specified in your Call Analytics request.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

MediaEncoding

Provides the media encoding you specified in your Call Analytics request.

Valid Values: pcm | ogg-opus | flac

MediaSampleRateHertz

Provides the sample rate that you specified in your Call Analytics request.

Valid Range: Minimum value of 8000. Maximum value of 48000.

PartialResultsStability

Provides the stabilization level used for your transcription.

Valid Values: high | medium | low

PiiEntityTypes

Lists the PII entity types you specified in your Call Analytics request.

Length Constraints: Minimum length of 1. Maximum length of 300.

Pattern: ^[A-Z_, ]+

RequestId

Provides the identifier for your real-time Call Analytics request.

SessionId

Provides the identifier for your Call Analytics transcription session.

Length Constraints: Fixed length of 36.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}

VocabularyFilterMethod

Provides the vocabulary filtering method used in your Call Analytics transcription.

Valid Values: remove | mask | tag

VocabularyFilterName

Provides the name of the custom vocabulary filter that you specified in your Call Analytics request.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

VocabularyName

Provides the name of the custom vocabulary that you specified in your Call Analytics request.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

The following data is returned in JSON format by the service.

BadRequestException

One or more arguments to the StartStreamTranscription, StartMedicalStreamTranscription, or StartCallAnalyticsStreamTranscription operation was not valid. For example, MediaEncoding or LanguageCode used unsupported values. Check the specified parameters and try your request again.

Type: Exception

HTTP Status Code: 400

CategoryEvent

Provides information on matched categories that were used to generate real-time supervisor alerts.

Type: CategoryEvent object

ConflictException

A new stream started with the same session ID. The current stream has been terminated.

Type: Exception

HTTP Status Code: 409

InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing.

Type: Exception

HTTP Status Code: 500

LimitExceededException

Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.

Type: Exception

HTTP Status Code: 429

ServiceUnavailableException

The service is currently unavailable. Try your request later.

Type: Exception

HTTP Status Code: 503

UtteranceEvent

Contains set of transcription results from one or more audio segments, along with additional information per your request parameters. This can include information relating to channel definitions, partial result stabilization, sentiment, issue detection, and other transcription-related data.

Type: UtteranceEvent object

Errors

For information about the errors that are common to all actions, see Common Errors.

BadRequestException

One or more arguments to the StartStreamTranscription, StartMedicalStreamTranscription, or StartCallAnalyticsStreamTranscription operation was not valid. For example, MediaEncoding or LanguageCode used unsupported values. Check the specified parameters and try your request again.

HTTP Status Code: 400

ConflictException

A new stream started with the same session ID. The current stream has been terminated.

HTTP Status Code: 409

InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing.

HTTP Status Code: 500

LimitExceededException

Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.

HTTP Status Code: 429

ServiceUnavailableException

The service is currently unavailable. Try your request later.

HTTP Status Code: 503

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go v2

• AWS SDK for Java V2

• AWS SDK for JavaScript V3

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3