AWS S3 Connector Setup Guide¶
Overview¶
The AWS S3 Connector allows you to ingest conversation recordings and chatscripts/transcripts from a configured S3 folder periodically with a customizable schedule into Quality AI Express, allowing you to use the tool with third-party Contact Center as a Service (CCaaS) solutions.
What You Will Need¶
- S3 bucket with read permissions.
- CSV metadata files with conversation details
- Audio files (WAV/MP3) or chat transcripts (JSON).
- Quality AI Express platform access.
5-Minute Setup¶
- Enable Quality AI Express in platform settings.
- Upload test.csv to your S3 folder with sample data.
- Configure the S3 connector with bucket credentials and paths.
- Run validation tests to verify connectivity.
- Set processing schedule and monitor via logs.
Critical Requirements¶
- Stereo Audio: Single file with agent (left) + customer (right) channels.
- Mono Audio (Two separate files): One agent-only; one customer-only.
- Timestamps: ISO 8601 format with UTC timezone (YYYY-MM-DDTHH:MM:SSZ).
- Agent Emails: Must exactly match platform user accounts.
Need more details? See the following Detailed Setup Process.
Prerequisites¶
Complete the following checklist before starting the configuration:
AWS Environment Setup¶
- S3 bucket created in your preferred region.
- IAM user/role configured with read-only S3 permissions.
- Planned bucket folder structure (unified vs separate paths).
- Test audio/chat files prepared for validation.
Platform Prerequisites¶
- The Quality AI Express feature is enabled in settings.
- All agents onboarded with correct email addresses.
- Service queues are configured and ready for mapping.
- The user has Integrations & Extensions permissions.
Data Validation¶
- Audio files in WAV or MP3 format (maximum 50MB each).
- Audio split into separate agent/customer files, with one recording each (For mono recordings).
- All timestamps follow ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
- All recording URLs are accessible via HTTPS.
- CSV files contain all required metadata fields.
- Create
test.csvfile with sample data.
Quick Reference¶
Supported Recording Types¶
| Type | Format | Files per Conversation | Channel Assignment | Analytics Level |
| Stereo Voice | WAV/MP3 | 1 | Left=Agent, Right=Customer | Full Analytics |
| Mono Voice | WAV/MP3 | 2 (separate agent/customer) | N/A | Enhanced Analytics |
| Voice Transcripts | JSON | 1 | Pre-transcribed audio | Text Analytics |
| Chat Scripts | JSON | 1 | Message-level attribution | Full Text Analytics |
Minimum Required CSV Fields¶
conversationId, queueId, agentEmail, conversationStartTime, conversationEndTime,
recordingType, channelType, [recordingUrl/agentRecordings+customerRecordings/transcriptUrl/chatScriptUrl]
Field Name Key Differences by Type¶
-
Stereo Voice: Uses
recordingUrl,agentChannel,customerChannel. -
Mono Voice: Uses
agentRecordings+customerRecordings(both required in the same row). -
Voice Transcripts: Uses
transcriptUrl. -
Chat Scripts: Uses
chatScriptUrl. -
Provider Field: All types use
asrProvider(notasProvider).
Authentication Methods¶
-
Access Keys: Simple setup, good for single integrations.
-
IAM Roles: Enterprise-grade security, recommended for production.
Mono Recording Requirements (Critical)¶
Note
For mono recordings, you must have two separate audio files.
-
Supported (Two clean mono files)
-
conv-123456-agent.wav(agent audio only) -
conv-123456-customer.wav(customer audio only)`
-
-
Not Supported (Single mixed mono file)
conv-123456-mixed.wav(both speakers mixed)
Impact of Mixed Mono Audio on Accuracy
Single mixed mono files significantly reduce transcription accuracy without proper speaker diarization. Clean separation is essential for quality analytics.
Data Flow Architecture¶
Setup Process¶
Prerequisites¶
AWS Requirements¶
Your AWS environment must have:
-
S3 Bucket: An organized folder structure for audio/chat files.
-
Authentication: Access keys or an IAM role with read permissions.
-
Network Access: HTTPS URLs for all audio files.
Required IAM Permissions
json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::your-bucket-name",
"arn:aws:s3:::your-bucket-name/*"
]
}
]
}
Platform Prerequisites¶
-
User Management: All agents/supervisors onboarded with valid email addresses.
-
Queue Configuration: Service queues are pre-configured for mapping.
Configuration Schemas¶
CSV Metadata Formats¶
Stereo Voice Recordings¶
Configuration: recordingType = stereo and channelType = voice
Mono Voice Recordings¶
Configuration: recordingType = mono and channelType = voice
Critical: Mono recordings require two separate CSV entries and two audio files per conversation.
Voice Transcripts (Pre-transcribed Audio)¶
Configuration: recordingType = transcription and channelType = voice
Use Case: When you have pre-transcribed audio files and need to skip the speech-to-text processing.
| Field | Required/Optional | Type | Example | Notes |
conversationId
|
Required | String | conv-123456 | Unique identifier, max 50 chars |
agentEmail
|
Required | String | john.smith@company.com | Must exist in the platform, defaults to the default user |
conversationStartTime
|
Required | String | 2025-04-10T14:30:00Z | ISO 8601 with UTC timezone |
conversationEndTime
|
Required | String | 2025-04-10T14:32:45Z | The end time must follow the start time |
channelType
|
Required | String | voice | Always voice for audio transcripts |
recordingType
|
Required | String | transcription | Always transcription for pre-transcribed |
transcriptPath
|
Required | String | transcripts/voice-123.json | Path to JSON transcript file |
queueId
|
Required | String | support-tier1 | Must exist in the queue mapping |
language
|
Optional | String | en | ISO 639-1 format, defaults to en |
asProvider
|
Optional | String | microsoft | Original audio service provider |
Note
This format is for organizations that have already transcribed their voice recordings and need to import the text for analysis without re-processing the audio.
JSON Transcript Schema¶
Voice Transcript Format¶
json
{
"recognizedPhrases": [
{
"recognitionStatus": "Success",
"channel": 0,
"offset": "PT14S",
"duration": "PT2.4S",
"offsetInTicks": 140000000.0,
"durationInTicks": 24000000.0,
"durationMilliseconds": 2400,
"offsetMilliseconds": 14000,
"nBest": [
{
"confidence": 0.8205426,
"lexical": "yes one four three four two six",
"itn": "yes 143426",
"maskedITN": "yes one four three four two six",
"display": "Yes, 143426.",
"words": [
{
"word": "yes",
"offset": "PT14S",
"duration": "PT0.32S",
"offsetInTicks": 140000000.0,
"durationInTicks": 3200000.0,
"durationMilliseconds": 320,
"offsetMilliseconds": 14000,
"confidence": 0.51653963
},
{
"word": "one",
"offset": "PT14.32S",
"duration": "PT0.2S",
"offsetInTicks": 143200000.0,
"durationInTicks": 2000000.0,
"durationMilliseconds": 200,
"offsetMilliseconds": 14320,
"confidence": 0.65166444
}
]
}
]
}
]
}
Required Fields:
json
{
"recognizedPhrases": [
{
"channel": 0,
"offsetInTicks": 140000000.0,
"nBest": [
{
"lexical": "yes one four three four two six",
"words": [
{
"word": "yes",
"offsetInTicks": 140000000.0,
"durationInTicks": 3200000.0,
"confidence": 0.51653963
}
]
}
]
}
]
}
Chat Scripts (Live Chat Interactions)¶
Configuration: recordingType = transcription and channelType = chat
Use Case: For live chat interactions from web chat, messaging platforms, or chat-based customer service.
| Field | Required/Optional | Type | Example | Notes |
conversationId
|
Required | String | conv-123456 | Unique identifier, maximum 50 characters |
agentEmail
|
Required | String | john.smith@company.com | Must exist in the platform, defaults to the default user |
conversationStartTime
|
Required | String | 2025-04-10T14:30:00Z | ISO 8601 format |
conversationEndTime
|
Required | String | 2025-04-10T14:45:00Z | Must be after start time |
channelType
|
Required | String | chat | Always chat for text interactions |
recordingType
|
Required | String | transcription | Always transcription for chat |
transcriptPath
|
Required | String | transcripts/chat-123.json | Path to JSON transcript file |
queueId
|
Required | String | support-tier1 | Must exist in the queue mapping |
language
|
Optional | String | en-US | Defaults to en if not specified |
Note
Chat scripts include real-time messaging interactions from various platforms, including web chat, WhatsApp, Facebook Messenger, and so on.
JSON Transcript Schema¶
Chat Transcript Format¶
json
{
"1": {
"type": "AGENT",
"text": "Good afternoon, how can I help you today?",
"timestamp": 1749562206000,
"userId": "john.smith@company.com"
},
"2": {
"type": "USER",
"text": "I need help with my account balance.",
"timestamp": 1749562253142,
"userId": "customer_12345"
}
}
Required Fields:
-
type:AGENT,USER, orSYSTEM -
text: Message content -
timestamp: Unix timestamp in milliseconds -
userId: Participant identifier
Note
For conversations involving transfers across agents and queues, use the queueId of the queue where the conversation ended, and the agentEmail of the agent who terminated the conversation.
Step-by-Step Configuration¶
Step 1: Prepare S3 Environment¶
Option 1: Unified Path Structure¶
Option 2: Separate Paths¶
Validation Checkpoint (Data Preparation)¶
Verify your S3 setup:
-
All audio files are accessible via HTTPS URLs.
-
CSV files contain the required fields with correct headers.
-
Mono recordings have separate agent/customer files.
-
The
test.csvfile exists in each configured folder before the configuration. -
File sizes under 50MB each.
Step 2: Platform Configuration¶
-
Navigate to Connector Setup.
-
Navigate to Contact Center AI > Quality AI > Configure > Connectors.
-
Click + Add Connector > Amazon S3 > Connect.
-
Configure the following Basic Configuration.
-
Name: Enter a descriptive connector name.
-
AWS Region: Select your S3 bucket region.
-
Auth Type: Choose the authentication method.
-
-
Configure the Authentication Setup (For Access Keys).
- Enter Access key and Secret key.
-
Configure the IAM Role.
- Enter the IAM Role ARN.
-
Configure the following two Folder Paths.
a. Unified Path:
-
Unified Voice and Chat Path
-
Folder Path: s3://your-bucket/conversations/
b. Separate Paths:
-
Separate Voice and Chat Path
-
Voice Path: s3://your-bucket/voice-interactions/
-
Chat Path: s3://your-bucket/chat-interactions/
-
Validation Checkpoint (Connection Setup)¶
Test your configuration:
-
Click the Test tab in the connector configuration.
-
Expected results:
-
Authentication: Connected successfully.
-
File Path Access: S3 bucket accessible.
-
File Format: CSV format validated.
-
Metadata Validation: Required fields confirmed.
If any checks fail:
-
Authentication: Verify credentials and IAM permissions.
-
File Access: Check bucket name, region, and folder paths, and ensure file URLs are accessible.
-
Format/Metadata: Ensure the
test.csvexists with proper structure, and the column headers and timestamps should match the specified formats.
-
Step 3: Queue Mapping & Scheduling¶
-
Configure Queue Mapping
a. Navigate to the Queue tab.
b. Map CSV
queueIdvalues to Quality AI Express queues.c. Ensure exact string matches.
-
Set Processing Schedule
a. Navigate to the Schedule tab.
-
Interval: Choose frequency (minutes/hours/days).
-
Start Time: Set initial run time (UTC timezone).
b. Click Save to activate.
-
Validation Checkpoint (Final Configuration)¶
Verify Complete Setup:
- Queue mappings saved and validated.
- Processing schedule configured and active.
- The first ingestion job appears in the Log tab.
- No error messages in processing logs.
Success Indicators:
- Conversations appear in Quality AI Express dashboards.
- Analytics data populates for ingested interactions.
Troubleshooting Guide¶
Authentication Issues¶
| Problem | Symptoms | Solution |
| Invalid Credentials | Authentication failed error |
|
| Permission Denied | Access denied to S3 bucket |
|
Data Processing Issues¶
| Problem | Symptoms | Solution |
| Timestamp Errors | Invalid timestamp format |
|
File Access¶
Performance Expectations¶
- 3-5 minutes per conversation, depending on conversation duration, ASR transcription latency (for voice), and LLM response latency.