Call Recording Quickstart
Important
Functionality described in this document is currently in public preview. This preview version is provided without a service-level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
This quickstart gets you started with Call Recording for voice and video calls. To start using the Call Recording APIs, you must have a call in place. Make sure you're familiar with Calling client SDK and/or Call Automation to build the end-user calling experience.
Sample Code
You can download the sample app from GitHub
Prerequisites
- You need an Azure account with an active subscription.
- Deploy a Communication Service resource. Record your resource connection string.
- Subscribe to events via Azure Event Grid.
- Download the .NET SDK
Before you start
Call Recording APIs use exclusively the serverCallId
to initiate recording. There are a couple of methods you can use to fetch the serverCallId
depending on your scenario:
Call Automation scenarios
- When using Call Automation, you have two options to get the
serverCallId
:- Once a call is created, a
serverCallId
is returned as a property of theCallConnected
event after a call has been established. Learn how to Get CallConnected event from Call Automation SDK. - Once you answer the call or a call is created the
serverCallId
is returned as a property of theAnswerCallResult
orCreateCallResult
API responses respectively.
- Once a call is created, a
Calling SDK scenarios
- When using Calling Client SDK, you can retrieve the
serverCallId
by using thegetServerCallId
method on the call. Use this example to learn how to Get serverCallId from the Calling Client SDK.
Let's get started with a few simple steps!
1. Create a Call Automation client
Call Recording APIs are part of the Azure Communication Services Call Automation libraries. Thus, it's necessary to create a Call Automation client.
To create a call automation client, you'll use your Communication Services connection string and pass it to CallAutomationClient
object.
CallAutomationClient callAutomationClient = new CallAutomationClient("<ACSConnectionString>");
2. Start recording session with StartRecordingOptions using 'StartRecordingAsync' API
Use the serverCallId
received during initiation of the call.
- RecordingContent is used to pass the recording content type. Use audio
- RecordingChannel is used to pass the recording channel type. Use mixed or unmixed.
- RecordingFormat is used to pass the format of the recording. Use wav.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
RecordingContent = RecordingContent.Audio,
RecordingChannel = RecordingChannel.Unmixed,
RecordingFormat = RecordingFormat.Wav,
RecordingStateCallbackEndpoint = new Uri("<CallbackUri>");
};
Response<RecordingStateResult> response = await callAutomationClient.getCallRecording()
.StartRecordingAsync(recordingOptions);
2.1. Only for Unmixed - Specify a user on channel 0
To produce unmixed audio recording files, you can use the AudioChannelParticipantOrdering
functionality to specify which user you want to record on channel 0. The rest of the participants will be assigned to a channel as they speak. If you use RecordingChannel.Unmixed
but don't use AudioChannelParticipantOrdering
, Call Recording will assign channel 0 to the first participant speaking.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<ServerCallId>"))
{
RecordingContent = RecordingContent.Audio,
RecordingChannel = RecordingChannel.Unmixed,
RecordingFormat = RecordingFormat.Wav,
RecordingStateCallbackEndpoint = new Uri("<CallbackUri>"),
AudioChannelParticipantOrdering = { new CommunicationUserIdentifier("<ACS_USER_MRI>") }
};
Response<RecordingStateResult> response = await callAutomationClient.getCallRecording().StartRecordingAsync(recordingOptions);
The StartRecordingAsync
API response contains the recordingId
of the recording session.
3. Stop recording session using 'StopRecordingAsync' API
Use the recordingId
received in response of startRecordingWithResponse
.
var stopRecording = await callAutomationClient.GetCallRecording().StopRecordingAsync(recording.Value.RecordingId);
4. Pause recording session using 'PauseRecordingAsync' API
Use the recordingId
received in response of startRecordingWithResponse
.
var pauseRecording = await callAutomationClient.GetCallRecording ().PauseRecordingAsync(recording.Value.RecordingId);
5. Resume recording session using 'ResumeRecordingAsync' API
Use the recordingId
received in response of startRecordingWithResponse
.
var resumeRecording = await callAutomationClient.GetCallRecording().ResumeRecordingAsync(recording.Value.RecordingId);
6. Download recording File using 'DownloadToAsync' API
Use an Azure Event Grid web hook or other triggered action should be used to notify your services when the recorded media is ready for download.
An Event Grid notification Microsoft.Communication.RecordingFileStatusUpdated
is published when a recording is ready for retrieval, typically a few minutes after the recording process has completed (for example, meeting ended, recording stopped). Recording event notifications include contentLocation
and metadataLocation
, which are used to retrieve both recorded media and a recording metadata file.
Below is an example of the event schema.
{
"id": string, // Unique guid for event
"topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
"subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
"data": {
"recordingStorageInfo": {
"recordingChunks": [
{
"documentId": string, // Document id for for the recording chunk
"contentLocation": string, //Azure Communication Services URL where the content is located
"metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
"deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
"index": int, // Index providing ordering for this chunk in the entire recording
"endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
}
]
},
"recordingStartTime": string, // ISO 8601 date time for the start of the recording
"recordingDurationMs": int, // Duration of recording in milliseconds
"sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
},
"eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
"dataVersion": string, // "1.0"
"metadataVersion": string, // "1"
"eventTime": string // ISO 8601 date time for when the event was created
}
Use DownloadStreamingAsync
API for downloading the recorded media.
var recordingDownloadUri = new Uri(contentLocation);
var response = await callAutomationClient.GetCallRecording().DownloadStreamingAsync(recordingDownloadUri);
The downloadLocation
for the recording can be fetched from the contentLocation
attribute of the recordingChunk
. DownloadStreamingAsync
method returns response of type Response<Stream>
, which contains the downloaded content.
7. Delete recording content using 'DeleteRecordingAsync' API
Use DeleteRecordingAsync
API for deleting the recording content (for example, recorded media, metadata)
var recordingDeleteUri = new Uri(deleteLocation);
var response = await callAutomationClient.GetCallRecording().DeleteRecordingAsync(recordingDeleteUri);
Sample Code
You can download the sample app from GitHub
Prerequisites
- You need an Azure account with an active subscription.
- Deploy a Communication Service resource. Record your resource connection string.
- Subscribe to events via Azure Event Grid.
- Download the Java SDK
Before you start
Call Recording APIs use exclusively the serverCallId
to initiate recording. There are a couple of methods you can use to fetch the serverCallId
depending on your scenario:
Call Automation scenarios
- When using Call Automation, you have two options to get the
serverCallId
:- Once a call is created, a
serverCallId
is returned as a property of theCallConnected
event after a call has been established. Learn how to Get CallConnected event from Call Automation SDK. - Once you answer the call or a call is created the
serverCallId
is returned as a property of theAnswerCallResult
orCreateCallResult
API responses respectively.
- Once a call is created, a
Calling SDK scenarios
- When using Calling Client SDK, you can retrieve the
serverCallId
by using thegetServerCallId
method on the call. Use this example to learn how to Get serverCallId from the Calling Client SDK.
Let's get started with a few simple steps!
1. Create a Call Automation client
Call Recording APIs are part of the Azure Communication Services Call Automation libraries. Thus, it's necessary to create a Call Automation client.
To create a call automation client, you'll use your Communication Services connection string and pass it to CallAutomationClient
object.
CallAutomationClient callAutomationClient = new CallAutomationClientBuilder()
.connectionString("<acsConnectionString>")
.buildClient();
2. Start recording session with StartRecordingOptions using 'startRecordingWithResponse' API
Use the serverCallId
received during initiation of the call.
- RecordingContent is used to pass the recording content type. Use AUDIO
- RecordingChannel is used to pass the recording channel type. Use MIXED or UNMIXED.
- RecordingFormat is used to pass the format of the recording. Use WAV.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
.setRecordingChannel(RecordingChannel.UNMIXED)
.setRecordingFormat(RecordingFormat.WAV)
.setRecordingContent(RecordingContent.AUDIO)
.setRecordingStateCallbackUrl("<recordingStateCallbackUrl>");
Response<StartCallRecordingResult> response = callAutomationClient.getCallRecording()
.startRecordingWithResponse(recordingOptions, null);
2.1. Only for Unmixed - Specify a user on channel 0
To produce unmixed audio recording files, you can use the AudioChannelParticipantOrdering
functionality to specify which user you want to record on channel 0. The rest of the participants will be assigned to a channel as they speak. If you use RecordingChannel.Unmixed
but don't use AudioChannelParticipantOrdering
, Call Recording will assign channel 0 to the first participant speaking.
StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
.setRecordingChannel(RecordingChannel.UNMIXED)
.setRecordingFormat(RecordingFormat.WAV)
.setRecordingContent(RecordingContent.AUDIO)
.setRecordingStateCallbackUrl("<recordingStateCallbackUrl>")
.setAudioChannelParticipantOrdering(List.of(new CommunicationUserIdentifier("<participantMri>")));
Response<RecordingStateResult> response = callAutomationClient.getCallRecording()
.startRecordingWithResponse(recordingOptions, null);
The startRecordingWithResponse
API response contains the recordingId
of the recording session.
3. Stop recording session using 'stopRecordingWithResponse' API
Use the recordingId
received in response of startRecordingWithResponse
.
Response<Void> response = callAutomationClient.getCallRecording()
.stopRecordingWithResponse(response.getValue().getRecordingId(), null);
4. Pause recording session using 'pauseRecordingWithResponse' API
Use the recordingId
received in response of startRecordingWithResponse
.
Response<Void> response = callAutomationClient.getCallRecording()
.pauseRecordingWithResponse(response.getValue().getRecordingId(), null);
5. Resume recording session using 'resumeRecordingWithResponse' API
Use the recordingId
received in response of startRecordingWithResponse
.
Response<Void> response = callAutomationClient.getCallRecording()
.resumeRecordingWithResponse(response.getValue().getRecordingId(), null);
6. Download recording File using 'downloadToWithResponse' API
Use an Azure Event Grid web hook or other triggered action should be used to notify your services when the recorded media is ready for download.
An Event Grid notification Microsoft.Communication.RecordingFileStatusUpdated
is published when a recording is ready for retrieval, typically a few minutes after the recording process has completed (for example, meeting ended, recording stopped). Recording event notifications include contentLocation
and metadataLocation
, which are used to retrieve both recorded media and a recording metadata file.
Below is an example of the event schema.
{
"id": string, // Unique guid for event
"topic": string, // /subscriptions/{subscription-id}/resourceGroups/{group-name}/providers/Microsoft.Communication/communicationServices/{communication-services-resource-name}
"subject": string, // /recording/call/{call-id}/serverCallId/{serverCallId}
"data": {
"recordingStorageInfo": {
"recordingChunks": [
{
"documentId": string, // Document id for the recording chunk
"contentLocation": string, //Azure Communication Services URL where the content is located
"metadataLocation": string, // Azure Communication Services URL where the metadata for this chunk is located
"deleteLocation": string, // Azure Communication Services URL to use to delete all content, including recording and metadata.
"index": int, // Index providing ordering for this chunk in the entire recording
"endReason": string, // Reason for chunk ending: "SessionEnded", "ChunkMaximumSizeExceeded”, etc.
}
]
},
"recordingStartTime": string, // ISO 8601 date time for the start of the recording
"recordingDurationMs": int, // Duration of recording in milliseconds
"sessionEndReason": string // Reason for call ending: "CallEnded", "InitiatorLeft”, etc.
},
"eventType": string, // "Microsoft.Communication.RecordingFileStatusUpdated"
"dataVersion": string, // "1.0"
"metadataVersion": string, // "1"
"eventTime": string // ISO 8601 date time for when the event was created
}
Use downloadToWithResponse
method of CallRecording
class for downloading the recorded media. Following are the supported parameters for downloadToWithResponse
method:
contentLocation
: Azure Communication Services URL where the content is located.destinationPath
: File location.parallelDownloadOptions
: An optional ParallelDownloadOptions object to modify how the - parallel download will work.overwrite
: True to overwrite the file if it exists.context
: A Context representing the request context.
Boolean overwrite = true;
ParallelDownloadOptions parallelDownloadOptions = null;
Context context = null;
String filePath = String.format(".\\%s.%s", documentId, fileType);
Path destinationPath = Paths.get(filePath);
Response<Void> downloadResponse = callAutomationClient.getCallRecording().downloadToWithResponse(contentLocation, destinationPath, parallelDownloadOptions, overwrite, context);
The content location and document IDs for the recording files can be fetched from the contentLocation
and documentId
fields respectively, for each recordingChunk
.
7. Delete recording content using ‘deleteRecordingWithResponse’ API.
Use deleteRecordingWithResponse
method of CallRecording
class for deleting the recorded media. Following are the supported parameters for deleteRecordingWithResponse
method:
deleteLocation
: Azure Communication Services URL where the content to delete is located.context
: A Context representing the request context.
Response<Void> deleteResponse = callAutomationClient.getCallRecording().deleteRecordingWithResponse(deleteLocation, context);
The delete location for the recording can be fetched from the deleteLocation
field of the Event Grid event.
Clean up resources
If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about cleaning up resources.
Next steps
For more information, see the following articles:
- Download our Java and .NET call recording sample apps
- Learn more about Call Recording
- Learn more about Call Automation
Feedback
Submit and view feedback for