Edit

Call recording: Bring your own Azure storage quickstart

  • Article

This quickstart gets you started with Bring your own Azure storage for Call Recording. To start using Bring your own Azure Storage functionality, make sure you're familiar with the Call Recording APIs.

Pre-requisite: Setting up Managed Identity and Role Based Access Controls(RBAC) role assignments

1. Enable system assigned managed identity for Azure Communication Services

Diagram showing a communication service resource with managed identity disabled

  1. Open your Azure Communication Services resource. Navigate to Identity on the left.
  2. Enabled System Assigned Managed Identity and click on Save.
  3. Once completed, you're able to see the Object principal ID of the newly created identity.

Diagram showing a communication service resource with managed identity enabled

  1. Once the identity has been successfully created, click on Azure role assignments to start adding role assignments.

2. Add role assignment

  1. Click on "Add role assignment"

Diagram showing a communication service resource managed identity adding role assignment

  1. On the "Add role assignment" panel, select the following values
    1. Scope: Storage
    2. Subscription: Choose your subscription
    3. Resource: Choose your storage account
    4. Role: Azure Communication Services needs "Storage Blob Data Contributor" to be able to write to your storage account.

Diagram showing a communication service resource managed identity adding role assignment details

  1. Click on "Save".
  2. Once completed, you see the newly added role assignment in the "Azure role assignment" window.

Diagram showing a communication service resource managed identity role assignment success

Start recording session with external storage specified

Use the server call ID received during initiation of the call.

Using Azure blob storage for external storage

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
{
    //...
    ExternalStorage = new BlobStorage(new Uri("<Insert Container / Blob Uri>"))
};
               
Response<RecordingStateResult> startRecordingWithResponse = await callAutomationClient.GetCallRecording()
        .StartRecordingAsync(options: recordingOptions);

Using Azure blob storage for external storage

StartRecordingOptions recordingOptions = new StartRecordingOptions(new ServerCallLocator("<serverCallId>"))
                .setExternalStorage(new BlobStorage("<Insert Container / Blob Uri>"));

Response<StartCallRecordingResult> response = callAutomationClient.getCallRecording()
.startRecordingWithResponse(recordingOptions, null);

Notification on successful export

Use an Azure Event Grid web hook, or other triggered action, to notify your services when the recorded media is ready and exported to the external storage location.

Refer to this 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": {
        "storageType": "string", // AzureBlob etc.
        "recordingId": "string", // unique id for recording
        "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
}

Folder Structure for Call Recording

Recordings are stored in the following format as shown in the diagram.

  • /YYYYMMDD/callId/first_8_of_recordingId + '-' + unique guid/[chunk-id]-acsmetadata.documentId.json
  • /YYYYMMDD/callId/first_8_of_recordingId + '-' + unique guid/[chunk-id]-audiomp3.documentId.mp3

Diagram showing a Call Recording Folder structure

Next steps

For more information, see the following articles: