vCon ElevenLabs Adapter

Convert ElevenLabs agent interactions to standardized vCon (Virtualized Conversation) format and export to multiple backends.

Features

• Extract conversation data from ElevenLabs.io API
• Transform conversations into standardized vCon format
• Export vCons to multiple backends:
  • Local filesystem
  • AWS S3 bucket
  • HTTP webhook endpoints
• Batch processing support
• Comprehensive logging and error handling
• Privacy-focused design with support for PII handling
• Configurable via YAML with environment variable substitution

Installation

Prerequisites

• Python 3.8+
• pip or conda
• ElevenLabs API key
• (Optional) AWS credentials for S3 export
• (Optional) Webhook endpoint for real-time notifications

Setup

git clone https://github.com/yourusername/vcon-eleven-labs-adapter.git
cd vcon-eleven-labs-adapter
pip install -r requirements.txt

Or with development dependencies:

pip install -e ".[dev]"

Quick Start

1. Configure Environment

Create a .env file from the example:

cp .env.example .env

Edit .env with your ElevenLabs API key and other settings.

2. Configure Pipeline

Create config.yml from the example:

cp config.yml.example config.yml

Edit to enable/disable exporters and set options.

3. Run Adapter

from src.adapter import ElevenLabsVconAdapter

adapter = ElevenLabsVconAdapter(config_file='config.yml')
vcons = adapter.process_all()

for vcon in vcons:
    print(f"Created vCon: {vcon.uuid}")

Configuration

Environment Variables

ELEVENLABS_API_KEY=your_api_key_here
ELEVENLABS_AGENT_IDS=agent_1,agent_2
EXPORT_DIR=./vcons
AWS_S3_BUCKET=my-bucket
WEBHOOK_URL=https://example.com/webhook
LOG_LEVEL=INFO

YAML Configuration

See config.yml.example for full options. Key sections:

ElevenLabs Settings

elevenlabs:
  api_key: ${ELEVENLABS_API_KEY}
  agent_ids: all
  poll_interval: 300
  batch_size: 10

File Export

exporters:
  file:
    enabled: true
    directory: ./vcons

S3 Export

exporters:
  s3:
    enabled: true
    bucket: my-bucket
    region: us-east-1
    prefix: elevenlabs/

Webhook Export

exporters:
  webhook:
    enabled: true
    url: https://example.com/vcon-receiver
    batch_size: 10
    retry_attempts: 3

Usage Examples

Basic Usage

from src.adapter import ElevenLabsVconAdapter

adapter = ElevenLabsVconAdapter(config_file='config.yml')
vcons = adapter.process_all()

Process Single Agent

adapter = ElevenLabsVconAdapter(config_file='config.yml')
vcons = adapter.process_agent('agent_id_123')

Batch Processing

adapter = ElevenLabsVconAdapter(config_file='config.yml')
agent_ids = ['agent_1', 'agent_2', 'agent_3']

for agent_id in agent_ids:
    vcons = adapter.process_agent(agent_id)
    print(f"Processed {len(vcons)} conversations for {agent_id}")

Export to Specific Backend

vcon = adapter.process_agent('agent_123')[0]

adapter.exporters['file'].export(vcon)
adapter.exporters['s3'].export(vcon)
adapter.exporters['webhook'].export(vcon)

vCon Structure

Each generated vCon contains:

• Parties: Agent and customer information
• Dialog: Audio recordings and/or transcripts
• Analysis: Optional transcripts, summaries (if available from ElevenLabs)
• Attachments: Call metadata, call records
• Metadata: UUID, timestamps, subject, source tags

Architecture

ElevenLabs API
    |
    v
ElevenLabsExtractor (extracts raw data)
    |
    v
PartyMapper (participant data)
    |
    v
DialogProcessor (conversation content)
    |
    v
VconBuilder (assemble complete vCon)
    |
    +----> FileExporter
    +----> S3Exporter
    +----> WebhookExporter

Error Handling

The adapter includes comprehensive error handling:

• Automatic retry on API rate limits
• Graceful degradation for missing optional fields
• Detailed error logging
• Continuation on non-fatal errors

Logging

Logging is configured in config.yml:

logging:
  level: INFO
  file: adapter.log
  console: true
  format: json

View logs:

tail -f adapter.log

Testing

Run tests:

pytest tests/ -v

With coverage:

pytest tests/ --cov=src --cov-report=html

Development

Project Structure

src/
  adapter.py                 # Main adapter class
  config.py                  # Configuration management
  logger.py                  # Logging setup
  extractors/
    elevenlabs_extractor.py  # ElevenLabs API client
  transformers/
    party_mapper.py          # Participant mapping
    dialog_processor.py      # Conversation processing
    vcon_builder.py          # vCon assembly
  exporters/
    file_exporter.py         # Filesystem export
    s3_exporter.py           # S3 export
    webhook_exporter.py      # Webhook export
  models/
    elevenlabs_models.py     # Data models

Contributing

1. Create a feature branch
2. Make changes
3. Add tests
4. Ensure all tests pass
5. Submit pull request

Privacy & Security

• PII is handled carefully; consider vCon encryption for sensitive data
• API keys should be stored in environment variables, never committed to version control
• S3 exports support encryption options (SSE-S3, SSE-KMS)
• Webhook exports should use HTTPS with proper authentication

Troubleshooting

ElevenLabs API Connection Issues

Check your API key and internet connection:

from src.extractors.elevenlabs_extractor import ElevenLabsExtractor
extractor = ElevenLabsExtractor(api_key='your_key')
agents = extractor.list_agents()

S3 Upload Failures

Verify AWS credentials and bucket permissions:

aws s3 ls s3://your-bucket/

Webhook Delivery Issues

Check webhook logs and verify endpoint is accessible:

curl -X POST https://your-webhook-url -H "Content-Type: application/json" -d '{}'

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions, please open an issue on GitHub or contact the maintainers.

References

• vCon Specification
• ElevenLabs API Documentation
• vCon Python Library