> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Blob Connector Setup Guide

[Back to Connectors](https://koreai.mintlify.site/ai-for-service/quality-ai/configurations.md#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.

| Section | Description |
| - | - |
| [Prerequisites](#prerequisites) | Azure storage account requirements and platform setup. |
| [Authentication Method](#authentication-method) | How to authenticate the connector using an Azure Storage connection string. |
| [Supported Data Types](#supported-data-types) | Voice and chat formats and file structure options. |
| [Set Up the Connector](#set-up-the-connector) | Steps to create, test, map queues, and schedule the connector. |
| [Troubleshooting](#troubleshooting) | Fixes for authentication failures, storage access errors, and data processing issues. |

## Prerequisites

### Azure Storage Requirements

| Requirement | Description |
| - | - |
| **Storage Account** | Azure Storage account with Blob access subscription. |
| **Authentication** | Service Principal (Recommended) or Connection String. |
| **Container** | Azure Blob container with conversation files. |
| **Supported File Types** | WAV, MP3, JSON, CSV. |
| **Maximum File Size** | 50 MB per file. |
| **Timestamp Format** | ISO 8601 UTC (`YYYY-MM-DDTHH:MM:SSZ`). |
| **File Accessibility** | Audio files must be reachable over HTTPS. |
| **Test File** | A `test.csv` file in each configured ingestion folder. |

### Platform Requirements

| Requirement | Description |
| - | - |
| **Quality AI Express** | Connector feature enabled in platform settings. |
| **Agent Setup** | Agents configured with valid email addresses matching platform accounts. |
| **Queue Setup** | Quality AI queues configured and available for mapping. |
| **Permissions** | Access to Connectors configuration or Integrations and Extensions. |

### Service Principal Permissions

Service Principal authentication requires the following Azure role assignment.

| Role | Scope | Purpose |
| - | - | - |
| **Storage Blob Data Reader** | Storage Account | Read and list blobs. |

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

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`

> [!NOTE]
>
> 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.

| Data Type | Format | Files per Conversation | Analytics | Channel Assignment |
| - | - | - | - | - |
| **Stereo Voice** | WAV, MP3 | 1 | Complete Analytics, Enhanced Analytics | Single dual-channel recording (Left = Agent, Right = Customer). |
| **Mono Voice** | WAV, MP3 | 2 | Complete Analytics, Enhanced Analytics | Separate agent and customer recordings. Mixed audio isn't supported. |
| **Voice Transcript** | JSON | 1 | Text Analytics, Complete Text Analytics | Pre-transcribed voice conversation. |
| **Chat Transcript** | JSON | 1 | Text Analytics, Complete Text Analytics | Message-level chat transcript. |

### 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`

| Field | Required | Type | Description |
| - | - | - | - |
| `conversationId` | Yes | String | Unique conversation identifier, maximum 50 characters. |
| `agentEmail` | Yes | String | Must match a platform user account. |
| `conversationStartTime` | Yes | String | ISO 8601 UTC timestamp. |
| `conversationEndTime` | Yes | String | ISO 8601 UTC timestamp; must be after start time. |
| `channelType` | Yes | String | Always `voice`. |
| `recordingType` | Yes | String | Always `stereo`. |
| `chatScriptUrl` | Yes\* | String | Full HTTPS URL to the JSON transcript. |
| `recordingUrl` | Yes | String | HTTPS URL to the audio recording. |
| `transcriptUrl` | Yes\* | String | Full HTTPS URL to the JSON transcript. |
| `queueId` | Yes | String | Must exist in queue mapping. |
| `agentChannel` | Yes | Integer | Agent channel: `0` or `1`. |
| `customerChannel` | Yes | Integer | Customer channel: `0` or `1`. |
| `language` | No | String | ISO 639-1 language code. Defaults to `en`. |
| `asprovider` | No | String | Audio service provider. |

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`.

| Field | Required | Type | Description |
| - | - | - | - |
| `conversationId` | Yes | String | Same identifier on both rows. |
| `agentEmail` | Yes | String | Must match a platform user account. |
| `conversationStartTime` | Yes | String | ISO 8601 UTC timestamp. |
| `conversationEndTime` | Yes | String | ISO 8601 UTC timestamp; must be after start time. |
| `channelType` | Yes | String | Always `voice`. |
| `recordingType` | Yes | String | Always `mono`. |
| `agentRecordings` | Yes | String | URL to the agent audio file. |
| `customerRecordings` | Yes | String | URL to the customer audio file. |
| `queueId` | Yes | String | Must exist in queue mapping. |
| `agentId` | No | String | Internal agent identifier. |
| `language` | No | String | ISO 639-1 language code. Defaults to `en`. |
| `asProvider` | No | String | Transcription provider. |

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`

| Field | Required | Type | Description |
| - | - | - | - |
| `conversationId` | Yes | String | Unique identifier, maximum 50 characters. |
| `agentEmail` | Yes | String | Must match a platform user account. |
| `conversationStartTime` | Yes | String | ISO 8601 UTC timestamp. |
| `conversationEndTime` | Yes | String | ISO 8601 UTC timestamp; must be after start time. |
| `channelType` | Yes | String | Always `voice`. |
| `recordingType` | Yes | String | Always `transcription`. |
| `transcriptPath` | Yes | String | Path to the JSON transcript file. |
| `queueId` | Yes | String | Must exist in queue mapping. |
| `language` | No | String | ISO 639-1 language code. Defaults to `en`. |
| `asProvider` | No | String | Original audio service provider. |

### Voice Transcript Field Requirements

The `recognizedPhrases` array contains phrase-level recognition information.

The following fields are mandatory:

| JSON Level | Required Fields |
| - | - |
| Phrase | `channel`, `offsetInTicks`, `nBest` |
| `nBest` alternative | `lexical`, `words` |
| Word | `word`, `offsetInTicks`, `durationInTicks`, `confidence` |

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`

| Field | Required | Type | Description |
| - | - | - | - |
| `conversationId` | Yes | String | Unique conversation identifier, maximum 50 characters. |
| `agentEmail` | Yes | String | Must match a platform user account. |
| `conversationStartTime` | Yes | String | ISO 8601 UTC timestamp. |
| `conversationEndTime` | Yes | String | ISO 8601 UTC timestamp. |
| `channelType` | Yes | String | Always `chat`. |
| `recordingType` | Yes | String | Always `transcription`. |
| `transcriptPath` | Yes | String | Path to the JSON transcript file. |
| `queueId` | Yes | String | Must exist in queue mapping. |
| `language` | No | String | Language code. Defaults to `en`. |

Example:

`transcripts/chat-123.json`

### Agent and Queue Validation

Additional processing rules for agent and queue onboarding.

| Agent Onboarded | Queue Onboarded | Processing Result |
| - | - | - |
| No | Yes | Conversation is processed. |
| Yes | Yes | Conversation is processed, even if the agent isn't mapped to the queue. |
| Any | No | Conversation is rejected. |

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`

| JSON Level | Required Fields |
| - | - |
| `Phrase` | `channel`, `offsetInTicks`, `nBest` |
| `nBest` | `lexical`, `words` |
| `Words` | `word`, `offsetInTicks`, `durationInTicks`, `confidence` |

### Chat Transcript

The root JSON object contains messages identified by numeric keys (for example, 1, 2, 3).

Each message requires the following fields:

| Field | Values | Description |
| - | - | - |
| `type` | `AGENT`, `USER`, `SYSTEM` | Identifies the speaker. |
| `text` | String | Message content. |
| `timestamp` | Unix time in milliseconds | Message timestamp. |
| `userId` | String | Agent email or customer ID. |

## Storage Structure Options

Choose a folder structure for your Azure Blob container before setting up the connector.

**Option A: Unified Path**

```text theme={null}
container/
├── metadata.csv
├── audio/
│   ├── conv-123456.wav
│   ├── conv-123457-agent.wav
│   └── conv-123457-customer.wav
├── chat/
│   └── chat-123459.json
└── test.csv
```

**Option B: Separate Voice and Chat Paths**

```text theme={null}
container/
├── voice/
│   ├── metadata.csv
│   ├── recordings/
│   └── test.csv
└── chat/
    ├── metadata.csv
    ├── transcripts/
    └── test.csv
```

**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:

| Credential | Where to Find It |
| - | - |
| **Application (client) ID** | Available under Essentials on the App Registration overview page. |
| **Directory (tenant) ID** | Available under Essentials on the App Registration overview page. |

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.

| Column | Action |
| - | - |
| **Value** | Copy this value. It's the Client Secret required by the connector. |
| **Secret ID** | Don't use this value. It's an internal identifier, not an authentication credential. |

> [!NOTE]
>
> 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**.

> [!NOTE]
>
> 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**.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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**.

#### Service Principal (Recommended)

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**.

> [!NOTE]
>
> 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:

   | Field | Description |
   | - | - |
   | **Interval Type** | Select the schedule frequency, such as minutes, hours, or days. |
   | **Start Date** | Specify the date on which the ingestion schedule should begin. |
   | **Repeat Every** | Define how frequently the connector should run based on the selected interval type. |
   | **Start Time** | Specify the time at which ingestion should begin. Use UTC. |

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.

| Column | Description |
| - | - |
| **Start Time** | Job start time. |
| **Finish Time** | Job completion time. |
| **Uploaded** | Number of uploaded files. |
| **Processing** | Number of processed files. |
| **Job Status** | Current processing status. |
| **View Details** | Opens job details. |

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

| Problem | Symptom | Resolution |
| - | - | - |
| **AuthorizationFailure** | Access is denied despite valid credentials. | Check the storage account firewall configuration. If network restrictions are enabled, add the Quality AI service outbound IP provided by your administrator to the allowlist. |
| **AADSTS7000215: Invalid client secret** | Service Principal authentication fails. | Verify that the Client Secret Value is correct and hasn't expired. Regenerate it if necessary. Don't use the Secret ID. |
| **AuthorizationPermissionMismatch** | The connector can't read or list Blob files. | Verify that `Storage Blob Data Reader` is assigned at the storage account scope. Allow up to 10 minutes for role assignments to propagate. |
| **Azure connection string is required** | The connector reports a missing connection string. | Enter the complete connection string from the Azure Storage Account Access Keys page. |
| **Invalid Azure connection string** | Azure rejects the connection string. | Copy the full connection string directly from Azure Access Keys without modifying it. |

### Storage Access Issues

| Problem | Symptom | Resolution |
| - | - | - |
| **Container Not Found** | Container or path not found. | Verify the container name and folder structure. |
| **File Not Available** | Blob access denied. | Verify blob access permissions and storage access settings. |

### File Validation Issues

| Problem | Symptom | Resolution |
| - | - | - |
| **File Format Validation Error** | Unsupported or invalid file format. | Verify the CSV metadata structure and required headers. |
| **Metadata Validation Error** | Missing or invalid metadata. | Verify required metadata fields and timestamp values. |

### Data Processing Issues

| Problem | Symptom | Resolution |
| - | - | - |
| **Timestamp Validation Error** | Invalid timestamp format. | Use ISO 8601 UTC format (`YYYY-MM-DDTHH:MM:SSZ`). |
| **Queue Mapping Error** | Queue IDs not mapped. | Map all queue IDs before running ingestion. |

### 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.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.