Workflows for recording calls - Amazon Chime SDK

Workflows for recording calls

The topics in this section list and describe the workflows for recording calls and Kinesis Video Streams.

Use this workflow when:

  • You already use, or plan to use, a Voice Connector to bring SIP media into call analytics.

    Note

    Voice Connectors support SIP and SIPREC. For more information, refer to Managing Amazon Chime SDK Voice Connectors, in the Amazon Chime SDK Administrator Guide.

  • You want to automatically record SIP or SIPREC calls with low latency to your choice of Amazon Simple Storage Service destinations.

  • You want to use the Amazon Chime SDK console to create the configuration and associate it with a Voice Connector.

  • You want to apply the same recording configuration to every Voice Connector call. If you want to apply multiple configurations to one or more Voice Connectors, refer to the next section.

To enable calling programmatically, use the following Amazon Chime SDK APIs.

For more information, see Configuring Voice Connectors to use call analytics in the Amazon Chime SDK Administrator Guide.

The following diagram shows the flow of data when a Voice Connector initiates a call recording session. Numbers in the diagram correspond to the numbered text below.

Image showing the flow of data when a Voice Connector starts recording a call.

In the diagram:

  1. Use the Amazon Chime SDK console or the CreateMediaInsightsPipelineConfiguration API to create a call analytics configuration. During the configuration creation process, you simply activate call recording, choose the desired recording file format, and specify the Amazon S3 destination for storing the recording files. For more information, refer to Creating call analytics configurations, in the Amazon Chime SDK Administrator Guide.

  2. You use the Amazon Chime SDK console or the PutVoiceConnectorStreamingConfiguration API to associate the configuration with a Voice Connector. To use the console, refer to Configuring Voice Connectors to use call analytics.

  3. During an outgoing call, the Voice Connector receives each call participant's audio.

  4. If a call analytics recording configuration is attached to the Voice Connector, the Voice Connector service uses the media pipeline service to initiate a call analytics recording session.

  5. The media pipeline service initiates the call recording processor that monitors the ongoing call.

  6. When the call ends, the media pipeline service delivers the call recording file to the designated Amazon S3 bucket and provides the recording metadata through the Amazon Kinesis Data Stream. If a data warehouse is enabled, the call metadata also goes to the Amazon Simple Storage Service data warehouse. In cases where SIPREC is utilized to incorporate SIP audio into call analytics, the call metadata includes SIPREC metadata in a table format. For more information on the recording tables, refer to Glue data catalog tables, later in this section.

  7. The media pipeline service sends the pipeline status events to the default Amazon EventBridge. For more information see, Using EventBridge notifications in this guide.

Note

Please note, you must enable Voice Connector streaming to enable recording with a Voice Connector. This feature enables streaming of call data to the Voice Connector managed Kinesis Video Streams in your account. For more information, refer to Streaming Amazon Chime SDK Voice Connector media to Kinesis Video Streams in the Amazon Chime SDK Administrator Guide.

You can also to store Voice Connector created call data in Kinesis Video Streams for varying durations, ranging from hours to days or even years. Opting for no data retention limits the usability of the call data for immediate consumption. The cost of Kinesis Video Streams is determined based on the bandwidth and total storage utilized. You can adjust the data retention period at any time within the Voice Connector streaming configuration. To enable call analytics recording, you must ensure that the Kinesis Video Stream retains the data long enough to conduct the call analytics. You do that by specifying a suitable data retention period.

You can associate a call insights pipeline configuration with as many Voice Connectors as you want. You can also create a different configuration for each Voice Connector. Voice Connectors use the AWSServiceRoleForAmazonChimeVoiceConnector to call the CreateMediaInsightsPipeline API on your behalf once per transaction ID. For information about the role, see Using the Amazon Chime SDK service-linked role for Amazon Chime SDK Voice Connectors in the Amazon Chime SDK Administrator Guide.

You record Amazon Kinesis Video streams when:

  • You need to apply different configurations to a call instead of using the same configuration for every Voice Connector call.

  • You want to record SIP or non-SIP audio that isn't processed by a Voice Connector.

To use this call recording option, you need to publish audio to Kinesis Video Streams (KVS) and then call the CreateMediaInsightsPipeline API with KVS stream channel information and a call analytics configuration ARN.

Note

The call analytics APIs support a maximum of two audio channels. You can also enable Voice Connector streaming, then use the KVS information published in the Voice Connector's EventBridge notifications to initiate a call recording.

When calling the CreateMediaInsightsPipeline API, you can choose whether or not to specify fragment numbers for each KVS stream channel definition. If you supply a fragment number, call analytics will begin processing the stream at that fragment. If you don't specify a fragment ID, call analytics begins processing the stream from the latest available fragment.

The following diagram shows the flow of data when a Voice Connector initiates a call recording session. Numbers in the diagram correspond to the numbered text below.

Image showing the flow of data when a Voice Connector starts recording a call.

In the diagram:

  1. You can use the Amazon Chime SDK console or the CreateMediaInsightsPipelineConfiguration API to the create a call recording configuration.

  2. Use the AWS SDK to create an application that pushes external audio into KVS, or enable Voice Connector streaming to publish call audio automatically to a KVS. For more information, see Streaming Amazon Chime SDK Voice Connector media to Kinesis Video Streams in the Amazon Chime SDK Administrator Guide.

  3. If Voice Connector streaming is enabled, the Voice Connector service sends notifications to the default EventBridge.

  4. In case of Voice Connector streaming, your application can use the Amazon Chime Voice Connector streaming STARTED events from EventBridge to gather KVS stream information about the legs of a call.

  5. Once your application has the audio information from Voice Connector streaming events or an external source, your application invokes the Amazon Chime SDK CreateMediaInsightsPipeline API.

  6. The media pipeline service initiates the call recording processor that monitors the ongoing call.

  7. The media pipeline service sends the pipeline status events to the default Amazon EventBridge. For more information, refer to Using EventBridge notifications.

  8. Once a call is completed, the media pipeline service will deliver the call recording file to the designated Amazon S3 bucket and provide the recording metadata through Amazon Kinesis Data Stream. If a data warehouse is enabled, the call metadata will also be sent to the Amazon S3 data warehouse. In cases where SIPREC is utilized to incorporate SIP audio into call analytics, the call metadata will include SIPREC metadata in a convenient table format. For more information on the recording tables, refer to Glue data catalog tables, later in this section.

  9. Your application can monitor the pipeline, and in case of a Voice Connector, the call status using events published to the Amazon EventBridge. For more information see, Using EventBridge notifications in this guide.

  10. To terminate recording, call the DeleteMediaPipeline API to terminate the call recording.

For API based recording and examples see, Amazon S3 recording sink in this guide.

The examples in this section explain how to do the following:

  • Use the CLI to run a call analytics configuration and invoke the CreateMediaInsightsPipeline.

  • Use the CLI to specify recording destinations audio file formats, and audio file names.

Running a configuration and starting a pipeline

Use the following command to run a configuration and start a media insights pipeline. The pipeline.json file contains the configuration settings.

aws chime-sdk-media-pipeline create-media-insights-pipeline --cli-input-json file://pipeline.json

The following example shows a typical pipeline.json file.

{
    "MediaInsightsPipelineConfigurationArn": arn:aws:chime:region;account_id:media-insights-pipeline-configuration/MyConfiguration,
    "KinesisVideoStreamRecordingSourceRuntimeConfiguration": {
        "Streams": [
            {
                "StreamArn": kinesis_video_stream_arn_1
            },
            {
                "StreamArn": kinesis_video_stream_arn_2
            }
        ],
        "FragmentSelector": {
            "FragmentSelectorType": "selector_type", // Specify "server_timestamp" or "producer_timestamp" as the fragment selector type
            "TimestampRange": {
                "StartTimestamp": epoch_time_seconds,
                "EndTimestamp": epoch_time_seconds
            }
        }
    },
    "S3RecordingSinkRuntimeConfiguration": {
        "Destination": arn:aws:s3:::bucket_name/prefix/optional_file_name,
        "RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format, if you want to override the configuration
    }
}

The MediaInsightsPipelineConfigurationArn is the configuration ARN that you receive after you create a call analytics configuration.

Setting destinations, names, and formats

The following example uses a folder named MyRecordingBucket as the S3SinkConfiguration.Destination value, and Opus as the RecordingFileFormat value.

arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.ogg

The following example uses MyRecordingBucket as the S3SinkConfiguration.Destination value, and Wav as the RecordingFileFormat value.

arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.wav