Skip to main content
Back to Connectors Set up the Azure Blob Storage connector to import conversation recordings, transcripts, and metadata from Azure Blob Storage into Quality AI Express. The Connector imports conversation recordings, transcripts, and metadata from Microsoft Azure Blob Storage into Quality AI Express on a configurable schedule. This also supports voice and chat interactions from third-party CCaaS platforms and processes data on a configurable schedule.

Prerequisites

Azure Storage Requirements

Platform Requirements

Service Principal Permissions

Service Principal authentication requires the following Azure role assignment. Assign this role at the storage account level, not just at the container level. Navigate to: Storage Account > Access Control (IAM) > Add role assignment. Avoid assigning broader permissions such as Contributor or Owner.

Authentication Methods

The connector supports two authentication methods. Service Principal provides identity-based authentication using an Azure App Registration. The following credentials are required:
  • Tenant ID
  • Client ID
  • Client Secret
  • Storage Account Name
The App Registration must have the Storage Blob Data Reader role assigned to the storage account.

Connection String

The connector authenticates with Azure Blob Storage using a connection string. To obtain the connection string:
  1. Open the Azure portal.
  2. Navigate to Storage Account.
  3. Select the required storage account.
  4. Go to Security + Networking > Access Keys.
  5. Copy the Connection String for Key1 or Key2.
  6. Use the connection string while configuring the connector.
Example format: DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
The fields displayed in the connector vary depending on the selected Auth Type.

Supported Data Types

The connector supports stereo voice, mono voice, voice transcripts, and chat transcripts.

Stereo Voice

A stereo recording contains both agent and customer audio in a single dual-channel recording.
  • Left channel: Agent.
  • Right channel: Customer.
  • One audio file per conversation.
Channel assignments must be represented correctly in the CSV metadata using agentChannel and customerChannel.

Mono Voice

Mono conversations require two separate audio files:
  • Agent recording
  • Customer recording
Example:
  • conv-123456-agent.wav
  • conv-123456-customer.wav
A single mixed mono recording isn’t supported. Each mono conversation must have two CSV rows sharing the same conversationId.

Voice Transcripts

Voice transcripts allow importing previously transcribed voice conversations without reprocessing the original audio.
  • Format: JSON.
  • One transcript file per conversation.
  • recordingType = transcription.
  • channelType = voice.

Chat Transcripts

Chat transcripts support conversations from platforms such as:
  • Web Chat, WhatsApp, Facebook Messenger, and other supported messaging platforms.
  • Format: JSON.
  • One transcript file per conversation.
  • recordingType = transcription.
  • channelType = chat.

Data Flow

The Azure Blob Storage connector imports conversation recordings, transcripts, and metadata into Quality AI Express through the following process:
  1. Azure Blob Storage: Stores audio recordings, voice transcripts, chat transcripts, and CSV metadata files.
  2. Connector Authentication: The connector authenticates with Azure Blob Storage using the configured Service Principal or Connection String.
  3. Data Ingestion: The connector accesses the configured Blob container and retrieves the metadata and associated conversation files.
  4. Conversation Processing: Quality AI Express processes the ingested conversations. Audio recordings are transcribed and analyzed, while existing transcripts are processed as text.
  5. Analytics: Processed conversations become available in Quality AI Express dashboards for quality evaluation, sentiment analysis, topic identification, and other supported analytics.

CSV Metadata Formats

This section defines the required CSV metadata fields for each supported conversation type. Core fields are shared across conversation types, while recording-specific fields differ.

Common Metadata Requirements

The following requirements apply when preparing metadata CSV files:
  • Conversation start and end timestamps must use ISO 8601 UTC format.
  • The conversation end time must be later than the conversation start time.
  • The agentEmail must match a valid platform user account.
  • The queueId must match an existing Quality AI Express queue mapping.
  • The conversationId must not exceed 50 characters.
  • Language defaults to en when the optional language field is omitted.
For mono recordings, both CSV rows must share the same conversationId and reference the corresponding agent and customer recordings.

Stereo Voice

  • recordingType = stereo
  • channelType = voice
Confirm whether both chatScriptUrl and transcriptUrl are required for stereo recordings in the deployed connector version.

Mono Voice

  • recordingType = mono
  • channelType = voice
Each conversation requires two CSV rows and two audio files. Both rows must share the same conversationId. The following example illustrates how to structure the CSV metadata for a mono voice conversation, where two rows share the same conversationId and reference separate agent and customer audio recordings. conversationId, agentEmail, conversationStartTime, conversationEndTime, channelType, recordingType, agentRecordings, customerRecordings, queueId, agentId, language, asProvider conv-123456, agent@example.com, 2025-04-10T14:30:00Z, 2025-04-10T14:45:00Z, voice, mono, https://example.com/agent.wav, https://example.com/customer.wav

Mono Recording Requirements

Mono conversations must contain two separate audio recordings:
  • One recording for the agent.
  • One recording for the customer.
Both recordings must be associated with the same conversation identifier in the metadata CSV. Example filenames:
  • conv-123456-agent.wav
  • conv-123456-customer.wav
A single mixed mono recording isn’t supported and may reduce transcription accuracy.

Stereo Recording Requirements

Stereo recordings contain both agent and customer audio in one dual-channel audio file. The CSV metadata must identify the correct channel assignment:
  • agentChannel: Agent audio channel (0 or 1).
  • customerChannel: Customer audio channel (0 or 1).
The channel assignments must correctly identify the agent and customer audio.

Voice Transcripts

  • recordingType = transcription
  • channelType = voice

Voice Transcript Field Requirements

The recognizedPhrases array contains phrase-level recognition information. The following fields are mandatory: Other properties, including recognitionStatus, offset, duration, durationMilliseconds, offsetMilliseconds, confidence at the alternative level, itn, maskedITN, and display, may be included as applicable.

Chat Transcript Message Requirements

The root JSON object contains numbered message keys, such as "1", "2", and "3". Each message must contain:
  • type: AGENT, USER, or SYSTEM.
  • text: Message content.
  • timestamp: Unix timestamp in milliseconds.
  • userId: Agent email or customer identifier.

Chat Transcripts

  • recordingType = transcription
  • channelType = chat
Example: transcripts/chat-123.json

Agent and Queue Validation

Additional processing rules for agent and queue onboarding. For transferred conversations:
  • Use the queue where the conversation ended.
  • Use the email address of the agent who closed the conversation.
For conversations transferred between agents or queues, use the following metadata:
  • Queue ID: The queue where the conversation ended.
  • Agent Email: The email address of the agent who closed the conversation.
This ensures the conversation is associated with the final handling queue and closing agent.

JSON Transcript Schemas

Detailed JSON transcript structure and mandatory fields.

Voice Transcript

The root JSON object contains a recognizedPhrases array. Each phrase can include:
  • recognitionStatus
  • channel
  • offset
  • duration
  • offsetInTicks
  • durationInTicks
  • durationMilliseconds
  • offsetMilliseconds
  • nBest
  • words
Each nBest alternative can include:
  • confidence
  • lexical
  • itn
  • maskedITN
  • display
  • words
Each word can include:
  • word
  • offset
  • duration
  • offsetInTicks
  • durationInTicks
  • durationMilliseconds
  • offsetMilliseconds
  • confidence
  • Required fields

Chat Transcript

The root JSON object contains messages identified by numeric keys (for example, 1, 2, 3). Each message requires the following fields:

Storage Structure Options

Choose a folder structure for your Azure Blob container before setting up the connector. Option A: Unified Path
Option B: Separate Voice and Chat Paths
Azure Blob path format: azure://your-container/your-folder/ Important requirements:
  • File and folder names must not contain spaces or special characters.
  • Each configured ingestion path must contain a test.csv file.
  • Metadata CSV files must contain the required headers.
  • Mono recordings must have separate agent and customer files.
  • All referenced files must be accessible to the connector.

Storage Path and File Validation

Before configuring the connector, verify the following:
  • Each configured ingestion folder contains a test.csv file.
  • Each metadata CSV contains the required column headers.
  • Audio files are in WAV or MP3 format and don’t exceed 50 MB.
  • Referenced audio files are accessible over HTTPS.
  • Voice and chat transcript files are in JSON format.
  • File and folder names don’t contain spaces or special characters.
  • Mono conversations have separate agent and customer recordings.
  • The configured Azure Blob paths point to the correct ingestion folders.
The connector must be able to access the configured storage paths and the files referenced by the metadata.

Prepare Service Principal Authentication

Complete Azure App Registration and Service Principal configuration. Skip this section if you are using Connection String authentication. You need three values from Azure:
  • Tenant ID.
  • Client ID.
  • Client Secret.
You must also assign the Storage Blob Data Reader role to the App Registration. Step 1: Create an App Registration
  1. Go to Azure Portal.
  2. Search for Azure Active Directory, also known as Microsoft Entra ID.
  3. Select App registrations.
  4. Select + New registration.
  5. Configure the registration.
  6. Select Register.
After registering the application, open the App Registration overview page and copy the following values: Save both values securely. You will need them when configuring the connector.

Client Secret Expiration

When creating the client secret:
  • Enter a descriptive name, such as quality-ai-key.
  • Select an appropriate expiration period. The original setup recommendation is at least 12 months.
  • Copy the Client Secret Value immediately after creation.
  • Store the secret securely.
The Client Secret Value is displayed only once. If you lose it, create a replacement secret and update the connector configuration. Step 2: Create a Client Secret A client secret acts as the password that the App Registration uses to prove its identity.
  1. Open the App Registration you created.
  2. Select Certificates & secrets from the left navigation menu.
  3. Select the Client secrets tab.
  4. Select + New client secret.
  5. Enter a description, such as quality-ai-key.
  6. Select an expiration period of at least 12 months.
  7. Select Add.
The newly created secret appears in the table.
The Client Secret Value is visible only once. Copy it immediately and store it securely. If you navigate away without saving it, you must delete and recreate the secret. Don’t use the Secret ID in the connector configuration.
Step 3: Grant the App Registration Access to the Storage Account The App Registration doesn’t have access to Azure Blob Storage by default. Assign the required role at the storage account level.
  1. Open the Azure portal.
  2. Search for Storage accounts.
  3. Open the required storage account.
  4. Select Access Control (IAM) from the left navigation menu.
  5. Select + Add > Add role assignment.
  6. Under the Role tab:
    • Search for Storage Blob Data Reader.
    • Select the role.
    • Select Next.
  7. Under the Members tab:
    • Set Assign access to to User, group, or service principal.
    • Select + Select members.
    • Search for the App Registration name, such as quality-ai-connector.
    • Select the App Registration.
    • Select Select.
    • Select Review + assign.
    • Select Review + assign again to confirm.
The role assignment appears under Access Control (IAM) > Role assignments.
Role assignments can take up to 10 minutes to propagate. Wait for the permissions to become effective before testing the connector.
Minimum required permission: Storage Blob Data Reader at the storage account scope is sufficient. Don’t assign broader roles such as Contributor or Owner. Step 4: Configure the Storage Account Firewall (If Required) If the Azure Storage account has network access restrictions enabled, the Quality AI service may be blocked even when the authentication credentials and role assignments are correct. In this case, add the outbound IP address provided by your Kore.ai administrator to the storage account firewall allowlist.
  1. Open the required storage account in the Azure portal.
  2. Select Networking under Security + networking.
  3. Under Firewalls and virtual networks, check the network access configuration.
  4. If Enabled from selected virtual networks and IP addresses is selected:
    • Locate the Firewall section.
    • Enter the outbound IP address provided by your Kore.ai administrator in the Address range field.
  5. Select Save.
To determine whether this step is required, navigate to Networking > Public network access. If the storage account is configured to allow access only from selected virtual networks and IP addresses, the firewall must allow the Quality AI service’s outbound IP.

Set Up the Connector

Before you begin, verify that your Blob container is ready:
  • Upload all required files to Azure Blob Storage.
  • Metadata .csv files contain required fields and valid values.
  • Mono conversations have separate agent and customer files.
  • The container and folder paths are available.
  • A test.csv file exists in each ingestion path.
  • Blob permissions enable the connector to access the files.
File and folder names shouldn’t contain any spaces or special characters.

Step 1: Create the Connector

  1. Navigate to Quality AI > Configure > Connectors.
  2. Select + Add Connector > Azure Blob Storage > Connect.
  3. Enter a Name for the connector.
  4. Select the Azure Region for the storage account.
  5. Set Authentication Type to Connection String.
  1. If you select Service Principal, provide the following credentials:
Connection String If you select Connection String, provide the following: Example: DefaultEndpointsProtocol=https;AccountName=…;AccountKey=…;EndpointSuffix=core.windows.net
  1. Enter the Connection String from your Azure Storage account.
  2. Configure the storage paths:
    • Unified Path: Enter a single Blob path for both voice and chat data.
    • Separate Paths: Enter a Voice Path and a Chat Path.

Step 2: Test the Connection

  1. Select the Test tab.
  2. Select Test to run the validation checks.
  3. Verify that the following checks pass: Authentication, File Path Access, File Format Validation, and Metadata Validation.

Step 3: Map Queues

  1. Select the Queue tab.
  2. Map each queueId from the .csv files to a Quality AI Express queue. Values must match exactly.
  3. Select Save.
Every queue ID in the metadata file must map to an existing Quality AI Express queue before ingestion can run. Evaluation forms linked to mapped queues determine how interactions are evaluated.

Step 4: Configure the Schedule

Configure the ingestion schedule to determine when the connector retrieves and processes conversation files from Azure Blob Storage.
  1. Select the Schedule tab.
  2. Configure the following schedule settings:
  3. Review the schedule configuration.
  4. Select Save to activate the connector schedule.
After saving, verify that:
  • Queue mappings are saved and validated.
  • The ingestion schedule is active.
  • The first ingestion job appears in the Log tab.
  • The ingestion job completes without processing errors.
The setup is complete when conversations are successfully ingested and appear in Quality AI Express dashboards with their corresponding analytics data.

Step 5: Monitor Ingestion Jobs

Use the Log tab to monitor ingestion activity. Ingestion is successful when the uploaded and processed file counts match, the job shows as completed, and no errors appear in the job details.

Troubleshooting

Authentication Issues

Storage Access Issues

File Validation Issues

Data Processing Issues

Performance Considerations

Processing time also depends on Automatic Speech Recognition (ASR) latency for voice recordings, conversation duration, file size, LLM processing time, AI analysis complexity, and the number of conversations being ingested.