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 (Recommended)
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
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:- Open the Azure portal.
- Navigate to Storage Account.
- Select the required storage account.
- Go to Security + Networking > Access Keys.
- Copy the Connection String for Key1 or Key2.
- Use the connection string while configuring the connector.
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.
agentChannel and customerChannel.
Mono Voice
Mono conversations require two separate audio files:- Agent recording
- Customer recording
conv-123456-agent.wavconv-123456-customer.wav
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:- Azure Blob Storage: Stores audio recordings, voice transcripts, chat transcripts, and CSV metadata files.
- Connector Authentication: The connector authenticates with Azure Blob Storage using the configured Service Principal or Connection String.
- Data Ingestion: The connector accesses the configured Blob container and retrieves the metadata and associated conversation files.
- Conversation Processing: Quality AI Express processes the ingested conversations. Audio recordings are transcribed and analyzed, while existing transcripts are processed as text.
- 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
agentEmailmust match a valid platform user account. - The
queueIdmust match an existing Quality AI Express queue mapping. - The
conversationIdmust not exceed 50 characters. - Language defaults to
enwhen the optional language field is omitted.
conversationId and reference the corresponding agent and customer recordings.
Stereo Voice
recordingType = stereochannelType = voice
Confirm whether both
chatScriptUrl and transcriptUrl are required for stereo recordings in the deployed connector version.
Mono Voice
recordingType = monochannelType = voice
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.
conv-123456-agent.wavconv-123456-customer.wav
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 (0or1).customerChannel: Customer audio channel (0or1).
Voice Transcripts
recordingType = transcriptionchannelType = voice
Voice Transcript Field Requirements
TherecognizedPhrases 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, orSYSTEM.text: Message content.timestamp: Unix timestamp in milliseconds.userId: Agent email or customer identifier.
Chat Transcripts
recordingType = transcriptionchannelType = 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.
- Queue ID: The queue where the conversation ended.
- Agent Email: The email address of the agent who closed the conversation.
JSON Transcript Schemas
Detailed JSON transcript structure and mandatory fields.Voice Transcript
The root JSON object contains arecognizedPhrases array.
Each phrase can include:
recognitionStatuschanneloffsetdurationoffsetInTicksdurationInTicksdurationMillisecondsoffsetMillisecondsnBestwords
nBest alternative can include:
confidencelexicalitnmaskedITNdisplaywords
wordoffsetdurationoffsetInTicksdurationInTicksdurationMillisecondsoffsetMillisecondsconfidenceRequired 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 Pathazure://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.csvfile. - 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.csvfile. - 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.
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.
- Go to Azure Portal.
- Search for Azure Active Directory, also known as Microsoft Entra ID.
- Select App registrations.
- Select + New registration.
- Configure the registration.
- Select Register.
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.
- Open the App Registration you created.
- Select Certificates & secrets from the left navigation menu.
- Select the Client secrets tab.
- Select + New client secret.
- Enter a description, such as quality-ai-key.
- Select an expiration period of at least 12 months.
- Select Add.
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.
- Open the Azure portal.
- Search for Storage accounts.
- Open the required storage account.
- Select Access Control (IAM) from the left navigation menu.
- Select + Add > Add role assignment.
- Under the Role tab:
- Search for
Storage Blob Data Reader. - Select the role.
- Select Next.
- Search for
- 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.
Role assignments can take up to 10 minutes to propagate. Wait for the permissions to become effective before testing the connector.
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.
- Open the required storage account in the Azure portal.
- Select Networking under Security + networking.
- Under Firewalls and virtual networks, check the network access configuration.
- 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.
- 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
.csvfiles contain required fields and valid values. - Mono conversations have separate agent and customer files.
- The container and folder paths are available.
- A
test.csvfile 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
- Navigate to Quality AI > Configure > Connectors.
- Select + Add Connector > Azure Blob Storage > Connect.
- Enter a Name for the connector.
- Select the Azure Region for the storage account.
- Set Authentication Type to Connection String.
Service Principal (Recommended)
- If you select Service Principal, provide the following credentials:
- Enter the Connection String from your Azure Storage account.
- 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
- Select the Test tab.
- Select Test to run the validation checks.
- Verify that the following checks pass: Authentication, File Path Access, File Format Validation, and Metadata Validation.
Step 3: Map Queues
- Select the Queue tab.
- Map each
queueIdfrom the.csvfiles to a Quality AI Express queue. Values must match exactly. - 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.- Select the Schedule tab.
-
Configure the following schedule settings:
- Review the schedule configuration.
- Select Save to activate the connector schedule.
- 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.
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.