# Using call recording The call recording actions for SIP media applications enable you to build call recording and post-call transcription solutions for a variety of uses. For example, you can record customer-care calls and use them for training. You use the call recording actions in concert with your SIP media applications. You can also use the actions on-demand or in response to a SIP event. + To start on-demand recording of a call in your SIP media application, you use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice_chime_UpdateSipMediaApplication.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice_chime_UpdateSipMediaApplication.html) API to invoke your application and return the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartCallRecording.html) action. + To start call recording in response to a SIP event, you return the `StartCallRecording` action in your application. You can pause and resume an in-progress recording. To pause, use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PauseCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PauseCallRecording.html) action. To resume, use the `ResumeCallRecording` action. Each time you pause or resume a recording, the action captures a tone that indicates the pause or resumption. When you pause, the action records silence, which Amazon Chime SDK uses to track the length of the pause and include the pauses in your bill. You can pause and resume recording as often as needed. To stop call recording, you return the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopCallRecording.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopCallRecording.html) action. However, call recordings automatically stop when the call stops, and in that case you don’t need to explicitly return the `StopCallRecording` action. You can only start and stop recording once for an individual call leg. Amazon Chime SDK delivers call recordings to an Amazon S3 bucket that you select. The bucket must belong to your AWS account. Once a call stops, the SIP media application delivers the recording to the folder specified in the `Destination` parameter of the [StartCallRecording](start-call-recording.md) action. The Amazon Chime SDK records calls in an open WAV format. Calls that record incoming and outgoing tracks use stereo mode, with the incoming track in the left channel and the outgoing track on the right channel. If you record only the incoming or outgoing track, the system uses mono mode. **Note** Recordings made using this feature may be subject to laws or regulations regarding the recording of electronic communications. It is your and your end users’ responsibility to comply with all applicable laws regarding the recording, including properly notifying all participants in a recorded session or communication that the session or communication is being recorded, and obtaining their consent. ## Billing for call recording Amazon Chime SDK bills you per minute for the time that call recording is enabled for a call leg, and that time includes all pauses. You are billed for the call recording usage once the call recording is delivered to your Amazon S3 bucket. # Recording audio tracks You can record just the incoming or outgoing tracks of call, or both tracks of a call. This image shows a typical one-legged, or non-bridged, incoming call. ![\[An incoming call that only communicates with a SIP media application.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/call-record-sma-one-leg.png) The call only has one leg with a `callID` of **call-id-1**. The `INCOMING` audio track is the audio from the caller to the SIP media application. The `OUTGOING` audio track is the audio from the SIP media application to the caller. Your SIP media application specifies the `CallId` of the call that you want record. To record the participant who placed the call, you specify `INCOMING`. To record the participant who responds to a call, you specify `OUTGOING`. To record both participants, specify `BOTH`. This image shows a typical bridged call with two participants. ![\[An incoming call that communicates with a SIP media application and a second participant.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/call-record-sma-bridged.png) In this example, the call has two call legs, **call-id-1** and **call-id-2**, and **call-id-1** is bridged to **call-id-2**. This creates four audio tracks, the incoming and outgoing audio streams for both call IDs. You can specify which of the call IDs and audio tracks to record. For example, if you want to record the audio track from the called participant, you record the `INCOMING` audio track by specifying **call-id-2** as the `CallId` and `INCOMING` as the track. If you want to record everything that the caller hears, you record the `OUTGOING` audio track by specifying **call-id-1** as the `CallId` and `OUTGOING` as the track. If you want to record all of the audio that the `Caller` said and heard, you record `BOTH` audio tracks by specifying `call-id-1` as the `CallId` and `BOTH` as the track. # Sample use cases SIP media applications provide call recording actions as building blocks. They give you the flexibility to build call-recording solutions for your business use cases. The following cases illustrate some common usage scenarios. **Topics** + [ ## Case 1: Recording a one-legged call that involves SIP actions ](#recording-case-1) + [ ## Case 2: Selectively recording audio in a bridged call ](#recording-case-2) + [ ## Case 3: Recording multiple call legs ](#recording-case-3) + [ ## Case 4: On-demand recording with pause and resume ](#on-demand-pause-resume) ## Case 1: Recording a one-legged call that involves SIP actions You can record a caller and any audio generated by SIP media application actions, such as the [PlayAudio](play-audio.md) and [PlayAudioAndGetDigits](play-audio-get-digits.md) actions. During recording, if a caller presses a digit, the recording captures the tone of that digit. This example uses the `PlayAudioAndGetDigits` action, but the interactive voice response (IVR) can be a complex series of SIP media application actions. In this example, the SIP media application records both audio tracks between the caller and the SIP media application itself. The recording starts when the call is established, and it stops when the caller hangs up. Billing starts when the call is established, and it stops when the caller hangs up. ![\[Diagram of a SIP media application recording two audio tracks, in this case, between a caller and the app itself.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/sma-recording-case-1.png) ## Case 2: Selectively recording audio in a bridged call You can selectively record the audio track of a single call participant. You can use this feature to selectively enable call recording only for a specific participant. In this example, the SIP media application records the incoming audio tracks between the called party and the SIP media application itself by specifying **call-id-2** as the `CallId` and `INCOMING` as the track. The call recording starts when the caller is bridged to the called party, and that's also when billing starts. The recording stops when the called party hangs up, and that's also when billing ends. This recording only has the called party’s audio track. ![\[Diagram of a SIP media application selectively recording one track.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/sma-recording-case-2.png) ## Case 3: Recording multiple call legs You can record multiple call legs. For example, say you bridge a call to a participant. When that participant hangs up, the phone call is bridged to another participant. You can enable call recording for all three call legs. This example shows three separate recording files. The recording for the first call leg captures the conversation between the caller, your application, and the two participants that were bridged into the call. The recording for the second call leg captures the conversation between the caller and the first participant. The recording for the third call leg captures the conversation between the caller and the second participant. This case creates three call legs, and billing applies to the start and end of each call leg. Put another way, the system delivers three recordings to your S3 bucket, and you're billed for each. ![\[Diagram of a SIP media application recording multiple call legs.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/sma-recording-case-3.png) ## Case 4: On-demand recording with pause and resume You can start, stop, pause, and resume call recording on-demand using the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_UpdateSipMediaApplicationCall.html) API. You can build a client application that calls the `UpdateSipMediaApplicationCall` API and invokes your SIP media application to return call recording actions. Your end users use the client application to control the call recording. For example, in a call center, an agent would use a desktop client application to trigger call recording actions on-demand. In the call center example, the agent might ask the caller’s permission to record the phone call, and they can click in the client application to start recording once the caller agrees. In another example, the caller might need to provide information such as a social security number (SSN). However, the call center policy requires that the agent should not record information such as a customer’s SSN. The agent can click the application to pause the recording while the customer provides the information, then click again to resume the recording. Once the agent handles the caller’s request, the agent clicks the application to stop recording and hangs up the call. In this use case, the SIP media application records the audio tracks between the caller and SIP media application. Since the `call-id-1` leg is bridged to the `call-id-2` leg, the system records the audio on both legs, caller and called. The recording and the billing start when the `UpdateSipMediaApplicationCall` API invokes the `StartCallRecording` action. The recording and the billing stop when the `UpdateSipMediaApplicationCall` API invokes the `StopCallRecording` action. As a reminder, pausing the recording does not change its duration, and you're billed for all pauses. ![\[Diagram of a SIP media application recording on-demand with recording paused and resumed.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/sma-recording-on-demand.png) # Call recording actions for SIP media applications You can specify different call recording actions in a response from the AWS Lambda function of your SIP media application. The following topics provide example code and explain how to use the actions. **Topics** + [ # StartCallRecording ](start-call-recording.md) + [ # StopCallRecording ](stop-call-recording.md) + [ # PauseCallRecording ](pause-call-recording.md) + [ # ResumeCallRecording ](resume-call-recording.md) # StartCallRecording The `StartCallRecording` action starts the recording of a call leg. You start call recording in your SIP media applications, either on-demand or in response to a SIP event. + To start on-demand recording of a call, you use the `UpdateSipMediaApplication` API to invoke your application and return the `StartCallRecording` action. + To start call recording in response to a SIP event, you return the `StartCallRecording` action in your application. You specify whether you want to record the audio track for the incoming leg, the outgoing leg, or both. The following sections explain how to use the `StartCallRecording` action. **Note** Recordings made using this feature may be subject to laws or regulations regarding the recording of electronic communications. It is your and your end users’ responsibility to comply with all applicable laws regarding the recording, including properly notifying all participants in a recorded session or communication that the session or communication is being recorded, and obtaining their consent. **Topics** + [ ## Requesting a StartCallRecording action ](#request-start) + [ ## Specifying a recording destination ](#recording-destination) + [ ## Granting Amazon S3 bucket permissions ](#grant-s3-perms) + [ ## Action successful response ](#action-successful) + [ ## Action error response ](#action-error) ## Requesting a StartCallRecording action The following example shows how to request the `StartCallRecording` action for `BOTH` tracks. ``` { "SchemaVersion": "1.0", "Actions": [ { "Type": "StartCallRecording", "Parameters": { "CallId": "call-id-1", "Track": "BOTH", "Destination": { "Type": "S3", "Location": "valid-bucket-name-and-optional-prefix" } } } ] } ``` **CallId** *Description* – `CallId` of participant in the `CallDetails` of the AWS Lambda function invocation *Allowed values* – A valid call ID *Required* – Yes *Default value* – None **Track** *Description* – Audio `Track` of the call recording. *Allowed values* – `BOTH`, `INCOMING`, or `OUTGOING` *Required* – Yes *Default value* – None **Destination.Type** *Description* – Type of destination. Only Amazon S3 is allowed. *Allowed values* – Amazon S3 *Required* – Yes *Default value* – None **Destination.Location** *Description* – A valid Amazon S3 bucket and an optional Amazon S3 key prefix. The bucket must have permissions to the Amazon Chime SDK Voice Connector service principal, voiceconnector.chime.amazonaws.com. *Allowed values* – A valid Amazon S3 path for which Amazon Chime SDK has permisions to the `s3:PutObject` and `s3:PutObjectAcl` actions. *Required* – Yes *Default value* – None ## Specifying a recording destination Amazon Chime SDK delivers call recordings to your Amazon S3 bucket. The bucket must belong to your AWS account. You specify the bucket's location in the `Destination` parameter of the `StartCallRecording` action. The `Type` field in the the `Destination` parameter must be `S3`. The `Location` field consists of your Amazon S3 bucket, plus an optional object-key prefix in which the call recording is delivered. The SIP media application uses the specified `Location`, the call leg’s date and time, the transaction ID, and the call ID to format the Amazon S3 object key. The `StartCallRecording` action response returns the full Amazon S3 object key. When you only provide the Amazon S3 bucket in the `Location` field, the SIP media application appends a default prefix, `Amazon-Chime-SMA-Call-Recordings`, to the Amazon S3 path. The SIP media application also appends the year, month, and day of the call's start time to help organize the recordings. The following example shows the general format of an Amazon S3 path with the default prefix. This example uses `myRecordingBucket` as the `Location` value. ``` myRecordingBucket/Amazon-Chime-SMA-Call-Recordings/2019/03/01/2019–03–01–17–10–00–010_c4640e3b–1478–40fb-8e38–6f6213adf70b_7ab7748e–b47d–4620-ae2c–152617d3333c.wav ``` The following example shows the data represented in the call recording Amazon S3 path. ``` s3Bucket/Amazon-Chime-SMA-Call-Recordings/year/month/date/year-month-date-hour-minute-second-millisecond_transactionId_callId.wav ``` When you provide the Amazon S3 bucket and object key prefix in the `Location` field, the SIP media application uses your object-key prefix in the destination Amazon S3 path instead of the default prefix. The following example shows the general format of a call recording Amazon S3 path with your prefix. For example, you can specify myRecordingBucket/technicalSupport/english as the `Location`. ``` myRecordingBucket/technicalSupport/english/2019/03/01/2019–03–01–17–10–00–010_c4640e3b1478–40fb–8e38-6f6213adf70b_7ab7748e–b47d–4620–ae2c–152617d3333c.wav ``` The following example shows the data in the Amazon S3 path. ``` s3Bucket/yourObjectKeyPrefix/year/month/date/year-month-date-hour-minute-second-millisecond_transactionId_callId.wav ``` The recording sent to your Amazon S3 bucket contains additional [ Amazon S3 object metadata](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html) about the call leg. The following table lists the supported Amazon S3 object metadata. | Name | Description | | --- | --- | | transaction-id | Transaction ID of the phone call | | call-id | CallId of participant in the CallDetails of the AWS Lambda function invocation | | recording-duration | Call recording duration in seconds | | recording-audio-file-format | Call recording audio file format represented as internet media type | ## Granting Amazon S3 bucket permissions Your destination Amazon S3 bucket must belong to the same AWS account as your application. In addition, the action must give `s3:PutObject` and `s3:PutObjectAcl` permission to the Amazon Chime SDK Voice Connector service principal, `voiceconnector.chime.amazonaws.com`. The following example grants the appropriate permission. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "SIP media applicationRead", "Effect": "Allow", "Principal": { "Service": "voiceconnector.chime.amazonaws.com" }, "Action": [ "s3:PutObject", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::bucket-name/*", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] } ``` ------ The PSTN audio service reads and writes to your S3 bucket on behalf of your Sip Media Application. To avoid the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html), you can restrict S3 bucket permissions to a single SIP media application. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "SIP media applicationRead", "Effect": "Allow", "Principal": { "Service": "voiceconnector.chime.amazonaws.com" }, "Action": [ "s3:PutObject", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::bucket-name/*", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333", "aws:SourceArn": "arn:aws:chime:us-east-1:111122223333:sma/sip-media-application-id" } } } ] } ``` ------ ## Action successful response When the call recording is successfully started on a call leg, the SIP media application invokes an AWS Lambda function with the `ACTION_SUCCESSFUL` event type. The location of call recording is returned in the response. ``` { "SchemaVersion": "1.0", "Sequence": INTEGER, "InvocationEventType": "ACTION_SUCCESSFUL", "ActionData": { "Type" : "StartCallRecording", "Parameters": { "CallId": "call-id-1", "Track": "BOTH", "Destination": { "Type": "S3", "Location": "valid-bucket-name" } } "CallRecordingDestination": { "Type": "S3", "Location": "call-recording-bucket-and-key" } } "CallDetails": { ... } } ``` ## Action error response For validation errors, the SIP media application calls the AWS Lambda function with the appropriate error message. The following table lists the error messages. | Error | Message | Reason | | --- | --- | --- | | `InvalidActionParameter` | `CallId` parameter for action is invalid | Any parameter is invalid. | | `SystemException` | System error while running an action. | Another type of system error occurred while running an action. | When the action fails to record the media on a call leg, the SIP media application invokes an AWS Lambda function with the `ActionFailed` event type. The following example shows a typical error response. ``` { "SchemaVersion": "1.0", "Sequence": 5, "InvocationEventType": "ACTION_FAILED", "ActionData": { "Type" : "StartCallRecording", "Parameters": { "CallId": "call-id-1", "Track": "BOTH", "Destination": { "Type": "S3", "Location": "valid-bucket-name" } } "Error": "NoAccessToDestination: Error while accessing destination" } "CallDetails": { ... } } ``` See a working example on GitHub: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) # StopCallRecording The `StopCallRecording` action stops the recording of a call leg. Recording stops automatically when a call ends, and your application doesn't need to explicitly return the `StopCallRecording` action. Once recording for a call leg stops, it can’t start again, and the recording is delivered to the destination specified in the `StartCallRecording` action. The following example stops recording for the `call-id-1` call leg. ``` { "SchemaVersion": "1.0", "Actions":[ { "Type": "StopCallRecording", "Parameters": { "CallId": "call-id-1" } } ] } ``` **CallId** *Description* – `CallId` of participant in the `CallDetails` of the AWS Lambda function invocation *Allowed values* – A valid call ID *Required* – Yes *Default value* – None See a working example on GitHub: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) # PauseCallRecording The `PauseCallRecording` action pauses recording of a call leg. Each time you pause a recording, the recording captures a tone that indicates the pause. When you pause, the recording continues, but it only captures silence. Pausing the recording does not affect the total duration of the recording. You can pause and resume recording as often as needed. The following example pauses recording. ``` { "SchemaVersion": "1.0", "Actions":[ { "Type": "PauseCallRecording", "Parameters": { "CallId": "call-id-1" } } ] } ``` **CallId** *Description* – `CallId` of participant in the `CallDetails` of the AWS Lambda function invocation *Allowed values* – A valid call ID *Required* – Yes *Default value* – None See a working example on GitHub: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording) # ResumeCallRecording The `ResumeCallRecording` action resumes the recording of a call leg. Before the recording restarts, a brief tone is played. You can pause and resume a recording multiple times for the duration of the call leg. The following example resumes recording. ``` { "SchemaVersion": "1.0", "Actions":[ { "Type": "ResumeCallRecording", "Parameters": { "CallId": "call-id-1" } } ] } ``` **CallId** *Description* – `CallId` of participant in the `CallDetails` of the AWS Lambda function invocation *Allowed values* – A valid call ID *Required* – Yes *Default value* – None See a working example on GitHub: [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)