# Using Amazon EventBridge with Amazon Transcribe
With Amazon EventBridge, you can respond to state changes in your Amazon Transcribe jobs by initiating events in other AWS services. When a transcription job changes state, EventBridge automatically sends an event to an event stream. You create rules that define the events that you want to monitor in the event stream and the action that EventBridge should take when those events occur. For example, routing the event to another service (or target), which can then take an action. You could, for example, configure a rule to route an event to an AWS Lambda function when a transcription job has completed successfully. To define [EventBridge rules](#defining-rules), refer to the following sections.
You can receive notifications for events through multiple channels, including email, [Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) chat notifications, or [AWS Console Mobile Application](https://docs.aws.amazon.com/consolemobileapp/latest/userguide/what-is-consolemobileapp.html) push notifications. You can also see notifications in the [Console Notifications Center](https://console.aws.amazon.com/notifications/). If you want to set up notifications, you can use [AWS User Notifications](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html). AWS User Notifications supports aggregation, which can reduce the number of notifications you receive during specific events.
## Defining EventBridge rules
To define EventBridge rules, use the [AWS Management Console](https://console.aws.amazon.com/events). When you define a rule, use Amazon Transcribe as the service name. For an example of how to create an EventBridge rule, see [Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html).
Before using EventBridge, note the following definitions:
+ **Event**–An event indicates a change in the state of one of your transcription jobs. For example, when the `TranscriptionJobStatus` of a job changes from `IN_PROGRESS` to `COMPLETED`.
+ **Target**–A target is another AWS service that processes an event. For example, AWS Lambda or Amazon Simple Notification Service (Amazon SNS). A target receives events in JSON format.
+ **Rule**–A rule matches incoming events that you want EventBridge to watch for and routes them to a target or targets for processing. If a rule routes an event to multiple targets, all of the targets process the event in parallel. A rule can customize the JSON sent to the target.
Amazon EventBridge events are emitted on a best-effort basis. For more information about creating and managing events in EventBridge, see [Amazon EventBridge events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
The following is an example of an EventBridge rule for Amazon Transcribe that's initiated when a transcription job's status changes to `COMPLETED` or `FAILED`.
```
{
"source": [
"aws.transcribe"
],
"detail-type": [
"Transcribe Job State Change"
],
"detail": {
"TranscriptionJobStatus": [
"COMPLETED",
"FAILED"
]
}
}
```
The rule contains the following fields:
+ `source`–The source of the event. For Amazon Transcribe, this is always `aws.transcribe`.
+ `detail-type`–An identifier for the details of the event. For Amazon Transcribe, this is always `Transcribe Job State Change`.
+ `detail`–The new job status of the transcription job. In this example, the rule initiates an event when the job status changes to `COMPLETED` or `FAILED`.
## Amazon Transcribe events
Amazon EventBridge logs several Amazon Transcribe events:
+ [Transcription job events](#job-event)
+ [Language identification events](#lang-id-event)
+ [Call Analytics events](#analytics-event)
+ [Call Analytics post-call events](#analytics-stream-event)
+ [Vocabulary events](#vocab-event)
These events all contain the following shared fields:
+ `version`: The version of the event data. This value is always `0`.
+ `id`: A unique identifier generated by EventBridge for the event.
+ `detail-type`: An identifier for the details of the event. For example, `Transcribe Job State Change`.
+ `source`: The source of the event. For Amazon Transcribe this is always `aws.transcribe`.
+ `account`: The AWS account ID of the account that generated the API call.
+ `time`: The date and time the event is delivered.
+ `region`: The AWS Region in which the request is made.
+ `resources`: The resources used by the API call. For Amazon Transcribe, this field is always empty.
+ `detail`: Additional details about the event.
+ `FailureReason`: This field is present if the state or status changes to `FAILED`, and describes the reason for the `FAILED` state or status.
+ Each event type has additional unique fields that are displayed under `detail`. These unique fields are defined in the following sections after each event example.
### Transcription job events
When a job's state changes from `IN_PROGRESS` to `COMPLETED` or `FAILED`, Amazon Transcribe generates an event. To identify the job that changed state and initiate the event in your target, use the event's `TranscriptionJobName` field. An Amazon Transcribe event contains the following information. A `FailureReason` field is added under `detail` if your transcription job status is `FAILED`.
Note that this event applies only to the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html) API operation.
```
{
"version": "0",
"id": "event ID",
"detail-type":"Transcribe Job State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"TranscriptionJobName": "my-first-transcription-job",
"TranscriptionJobStatus": "COMPLETED" (or "FAILED")
}
}
```
+ `TranscriptionJobName`: The unique name you chose for your transcription job.
+ `TranscriptionJobStatus `: The status of the transcription job. This can be `COMPLETED` or `FAILED`.
### Language identification events
When you enable [automatic language identification](lang-id.md), Amazon Transcribe generates an event when the language identification state is `COMPLETED` or `FAILED`. To identify the job that changed state and initiate the event in your target, use the event's `JobName` field. An Amazon Transcribe event contains the following information. A `FailureReason` field is added under `detail` if your language identification status is `FAILED`.
Note that this event applies only to the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html) API operation when the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_LanguageIdSettings.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_LanguageIdSettings.html) parameter is included.
```
{
"version": "0",
"id": "event ID",
"detail-type": "Language Identification State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"JobType": "TranscriptionJob",
"JobName": "my-first-lang-id-job",
"LanguageIdentificationStatus": "COMPLETED" (or "FAILED")
}
}
```
+ `JobType`: For transcription jobs, this value must be `TranscriptionJob`.
+ `JobName`: The unique name of your transcription job.
+ `LanguageIdentificationStatus`: The status of language identification in a transcription job. This can be `COMPLETED` or `FAILED`.
### Call Analytics events
When a [Call Analytics](call-analytics.md) job state changes from `IN_PROGRESS` to `COMPLETED` or `FAILED`, Amazon Transcribe generates an event. To identify the Call Analytics job that changed state and initiates the event in your target, use the event's `JobName` field. An Amazon Transcribe event contains the following information. A `FailureReason` field is added under `detail` if your Call Analytics job status is `FAILED`.
Note that this event applies only to the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartCallAnalyticsJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartCallAnalyticsJob.html) API operation.
```
{
"version": "0",
"id": "event ID",
"detail-type": "Call Analytics Job State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"JobName": "my-first-analytics-job",
"JobStatus": "COMPLETED" (or "FAILED"),
"FailureReason": "failure reason", // only present when JobStatus is FAILED
"AnalyticsJobDetails": { // only when you enable optional features such as Generative Call Summarization
"Skipped": []
}
}
}
```
+ `JobName`: The unique name of your Call Analytics transcription job.
+ `JobStatus`: The status of your Call Analytics transcription job. This can be either `COMPLETED` or `FAILED`.
+ `FailureReason`: This field is present only when the `JobStatus` is `FAILED`, and describes the reason for the failure.
+ `AnalyticsJobDetails`: The details of your Call Analytics transcription job, including information about skipped analytics features.
### Call Analytics post-call events
When a [post-call analytics](tca-post-call.md) transcription changes state from `IN_PROGRESS` to `COMPLETED` or `FAILED`, Amazon Transcribe generates an event. To identify the Call Analytics post-call job that changed state and initiate the event in your target, use the event's `StreamingSessionId` field.
Note that this event applies only to the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartCallAnalyticsStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartCallAnalyticsStreamTranscription.html) API operation when the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_PostCallAnalyticsSettings.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_PostCallAnalyticsSettings.html) parameter is included.
A `COMPLETED` event contains the following information:
```
{
"version": "0",
"id": "event ID",
"detail-type": "Call Analytics Post Call Job State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"StreamingSessionId": "session-id",
"PostCallStatus": "COMPLETED",
"Transcript": {
"RedactedTranscriptFileUri": "s3://amzn-s3-demo-bucket/my-output-files/my-redacted-file.JSON",
"TranscriptFileUri": "s3://amzn-s3-demo-bucket/my-output-files/my-file.JSON"
},
"Media": {
"MediaFileUri": "s3://amzn-s3-demo-bucket/my-output-files/my-redacted-file.WAV",
"RedactedMediaFileUri": "s3://amzn-s3-demo-bucket/my-output-files/my-redacted-file.WAV"
}
}
}
```
A `FAILED` event contains the following information:
```
{
"version": "0",
"id": "event ID",
"detail-type": "Call Analytics Post Call Job State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"StreamingSessionId": "session-id",
"PostCallStatus": "FAILED"
}
}
```
+ `StreamingSessionId`: The identification number assigned to your real-time Call Analytics transcription request.
+ `PostCallStatus`: The status of your post-call Call Analytics transcription. This can be either `COMPLETED` or `FAILED`.
+ `Transcript`: The URI of your redacted and unredacted transcripts.
+ `Media`: The URI of your redacted and unredacted audio files.
### AWS HealthScribe post stream analytics events
When a state changes for a AWS HealthScribe post-stream analytics operation, such as a [ClinicalNoteGenerationResult](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_ClinicalNoteGenerationResult.html) changing from `IN_PROGRESS` to `COMPLETED`, AWS HealthScribe generates an event with the following information:
```
{
"version":"0",
"id":"event ID",
"detail-type":"MedicalScribe Post Stream Analytics Update",
"source":"aws.transcribe",
"account":"111122223333",
"time":"timestamp",
"region":"us-east-1",
"resources":[],
"detail":{
"SessionId": ,
"UpdateType": "ClinicalNoteGenerationResult",
"ClinicalNoteGenerationResult": {
"ClinicalNoteOutputLocation": s3://amzn-s3-demo-bucket/clinical-note-output-files/clinical-notes.JSON,
"TranscriptOutputLocation": s3://amzn-s3-demo-bucket/my-output-files/my-file.JSON,
"Status": ,
"FailureReason":
}
}
}
```
+ `UpdateType`: The type of post-stream analytics operation that generated the event. The content of the result object varies depending on the `UpdateType`.
+ `SessionId`: The identification number for your AWS HealthScribe stream. Use this ID to identify originating streaming session and then find the post-stream analytics that generated the event.
+ `Status`: The status of the post-stream analytics operation. This can be `IN_PROGRESS`, `COMPLETED`, or `FAILED`.
+ `ClinicalNoteOutputLocation`: The URI of the output Amazon S3 bucket for the `ClinicalNoteGenerationResult`.
+ `TranscriptOutputLocation`: The URI of your transcript.
### Vocabulary events
When a [custom vocabulary](custom-vocabulary.md)'s state changes from `PENDING` to `READY` or `FAILED`, Amazon Transcribe generates an event. To identify the custom vocabulary that changed state and initiate the event in your target, use the event's `VocabularyName` field. An Amazon Transcribe event contains the following information. A `FailureReason` field is added under `detail` if your custom vocabulary state is `FAILED`.
**Note**
This event applies only to the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateVocabulary.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateVocabulary.html) API operation.
```
{
"version": "0",
"id": "event ID",
"detail-type": "Vocabulary State Change",
"source": "aws.transcribe",
"account": "111122223333",
"time": "timestamp",
"region": "us-west-2",
"resources": [],
"detail": {
"VocabularyName": "unique-vocabulary-name",
"VocabularyState": "READY" (or "FAILED")
}
}
```
+ `VocabularyName`: The unique name of your custom vocabulary.
+ `VocabularyState`: The processing state of your custom vocabulary. This can be `READY` or `FAILED`.